@j0hanz/filesystem-mcp 2.6.3 → 2.7.0

package/dist/core/store.js.map

@@ -1 +1 @@
-{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/core/store.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ContentBlock } from '@modelcontextprotocol/server';\n\nimport { randomUUID } from 'node:crypto';\n\nimport { ErrorCode, FsError } from './errors.ts';\nimport { MIB } from './util.ts';\n\n// ─── TTL + LRU map ───────────────────────────────────────────────────────────\n\n/**\n * A bounded, expiring map. `Map` keeps insertion order and a read re-inserts,\n * so the first key is always the least recently used one. Entries carry an\n * optional weight so a byte budget can be enforced next to the entry cap.\n */\nclass TtlLru<V> {\n  readonly #byKey = new Map<string, { value: V; expiresAt: number; weight: number }>();\n  readonly #maxEntries: number;\n  readonly #maxWeight: number;\n  readonly #ttlMs: number;\n  readonly #now: () => number;\n  #weight = 0;\n\n  constructor(opts: { maxEntries: number; ttlMs: number; maxWeight?: number; now?: () => number }) {\n    this.#maxEntries = opts.maxEntries;\n    this.#maxWeight = opts.maxWeight ?? Number.POSITIVE_INFINITY;\n    this.#ttlMs = opts.ttlMs;\n    this.#now = opts.now ?? Date.now;\n  }\n\n  /** Drop every expired entry; true when at least one went. */\n  prune(): boolean {\n    const now = this.#now();\n    const before = this.#byKey.size;\n    for (const [key, entry] of this.#byKey) {\n      if (entry.expiresAt <= now) this.delete(key);\n    }\n    return this.#byKey.size !== before;\n  }\n\n  /** The live value, bumped to most recently used; `undefined` when missing or expired. */\n  get(key: string): V | undefined {\n    const entry = this.#byKey.get(key);\n    if (!entry) return undefined;\n    if (entry.expiresAt <= this.#now()) {\n      this.delete(key);\n      return undefined;\n    }\n    this.#byKey.delete(key);\n    this.#byKey.set(key, entry);\n    return entry.value;\n  }\n\n  /** Insert (pruning expired first) and evict least recently used entries past either cap. */\n  set(key: string, value: V, weight = 0): void {\n    this.prune();\n    this.delete(key);\n    this.#byKey.set(key, { value, expiresAt: this.#now() + this.#ttlMs, weight });\n    this.#weight += weight;\n    while (\n      this.#byKey.size > 0 &&\n      (this.#byKey.size > this.#maxEntries || this.#weight > this.#maxWeight)\n    ) {\n      const oldest = this.#byKey.keys().next();\n      if (oldest.done) break;\n      this.delete(oldest.value);\n    }\n  }\n\n  delete(key: string): void {\n    const entry = this.#byKey.get(key);\n    if (!entry) return;\n    this.#weight -= entry.weight;\n    this.#byKey.delete(key);\n  }\n\n  /** Live keys, least recently used first. Prunes expired entries first. */\n  keys(): string[] {\n    this.prune();\n    return [...this.#byKey.keys()];\n  }\n\n  clear(): void {\n    this.#byKey.clear();\n    this.#weight = 0;\n  }\n}\n\n// ─── Resource store: externalized tool results ───────────────────────────────\n\ninterface ResourceEntry {\n  uri: string;\n  name: string;\n  mimeType: string;\n  size: number;\n  expiresAt: string;\n  text: string;\n}\n\nconst MAX_ENTRIES = 64;\nconst MAX_TOTAL_BYTES = 25 * MIB;\nconst MAX_ENTRY_BYTES = 10 * MIB;\nconst ENTRY_TTL_MS = 60 * 1000;\n\nexport class ResourceStore {\n  readonly #entries = new TtlLru<ResourceEntry>({\n    maxEntries: MAX_ENTRIES,\n    maxWeight: MAX_TOTAL_BYTES,\n    ttlMs: ENTRY_TTL_MS,\n  });\n  readonly #onListChanged: (() => void) | undefined;\n\n  constructor(onListChanged?: () => void) {\n    this.#onListChanged = onListChanged;\n  }\n\n  getEntry(uri: string): ResourceEntry {\n    const entry = this.#entries.get(uri);\n    if (entry) return entry;\n    // Not found and expired share a remedy; only the wording differs, and an\n    // expiry seen here changed the list a client may hold.\n    if (this.#entries.prune()) this.#onListChanged?.();\n    throw new FsError(\n      ErrorCode.NOT_FOUND,\n      `Resource not found: ${uri}. Re-run the tool to regenerate.`,\n    );\n  }\n\n  putText(params: { name: string; mimeType?: string; text: string }): ResourceEntry {\n    const entryBytes = Buffer.byteLength(params.text, 'utf8');\n    if (entryBytes > MAX_ENTRY_BYTES) {\n      if (this.#entries.prune()) this.#onListChanged?.();\n      throw new FsError(ErrorCode.TOO_LARGE, `Resource too large to cache (${entryBytes} bytes).`);\n    }\n    const entry: ResourceEntry = {\n      uri: `filesystem-mcp://result/${randomUUID()}`,\n      name: params.name,\n      mimeType: params.mimeType ?? 'text/plain',\n      size: entryBytes,\n      expiresAt: new Date(Date.now() + ENTRY_TTL_MS).toISOString(),\n      text: params.text,\n    };\n    this.#entries.set(entry.uri, entry, entryBytes);\n    this.#onListChanged?.();\n    return entry;\n  }\n\n  /**\n   * Live URIs, oldest first. Deliberately silent about the prune it runs:\n   * this is the read path `resources/list` runs through, and the caller is\n   * already receiving the post-prune list.\n   */\n  keys(): string[] {\n    return this.#entries.keys();\n  }\n}\n\nexport interface JsonResourceResult {\n  entry: {\n    uri: string;\n    size: number;\n    mimeType: string;\n    expiresAt: string;\n  };\n  link: ContentBlock;\n}\n\n/**\n * Owner of the externalize-a-payload rule: a tool whose inline response is\n * truncated publishes the full value to the resource store as pretty-printed\n * JSON and hands back the URI to reach it by, plus the link block that offers\n * it to the user.\n */\nexport function putJsonResource(\n  store: ResourceStore,\n  name: string,\n  // `Record<string, unknown> | readonly unknown[]`, not `unknown` or `object`:\n  // JSON.stringify returns undefined for undefined and for functions, and `null`\n  // is excluded so non-string payloads cannot enter the store's text entry.\n  value: Record<string, unknown> | readonly unknown[],\n): JsonResourceResult {\n  const entry = store.putText({\n    name,\n    mimeType: 'application/json',\n    text: JSON.stringify(value, null, 2),\n  });\n\n  return {\n    entry: {\n      uri: entry.uri,\n      size: entry.size,\n      mimeType: entry.mimeType,\n      expiresAt: entry.expiresAt,\n    },\n    link: {\n      type: 'resource_link',\n      uri: entry.uri,\n      name: entry.name,\n      mimeType: entry.mimeType,\n      size: entry.size,\n      annotations: { audience: ['user'] },\n    },\n  };\n}\n\n// ─── Page snapshots: paginated result sets ───────────────────────────────────\n\nexport interface PageSnapshot<T = unknown, M = unknown> {\n  readonly items: readonly T[];\n  readonly metadata: M;\n}\n\n/**\n * The one cursor rejection: a cursor whose snapshot expired, was evicted, was\n * already consumed past its end, or belongs to a different query. Every case\n * has the same remedy, so they share one message.\n */\nexport function invalidCursor(): FsError {\n  return new FsError(\n    ErrorCode.INVALID_INPUT,\n    'Invalid cursor. Request the first page without a cursor.',\n  );\n}\n\n/**\n * Short-lived snapshots of a completed query's full result set, so later pages\n * slice a stored array instead of re-scanning and re-sorting the filesystem.\n *\n * ponytail: bounded by snapshot count and TTL, not by bytes — 32 x 20,000\n * `list` entries or 32 x 10,000 `search_text` matches, each match retaining up\n * to 20 more line strings at `context: 10`, order of a few hundred MB held for\n * 60s, and the HTTP leg shares one store so any caller can drive it. If that\n * shows up as memory pressure, pass a byte weight to `set` the way\n * `ResourceStore` does.\n */\nexport class PageSnapshotStore {\n  readonly #byId: TtlLru<PageSnapshot & { queryKey: string }>;\n\n  constructor(options: { maxSnapshots?: number; ttlMs?: number; now?: () => number } = {}) {\n    this.#byId = new TtlLru({\n      maxEntries: options.maxSnapshots ?? 32,\n      ttlMs: options.ttlMs ?? 60 * 1000,\n      ...(options.now ? { now: options.now } : {}),\n    });\n  }\n\n  create(params: { queryKey: string; items: readonly unknown[]; metadata?: unknown }): string {\n    const snapshotId = randomUUID();\n    this.#byId.set(snapshotId, {\n      queryKey: params.queryKey,\n      items: params.items,\n      metadata: params.metadata,\n    });\n    return snapshotId;\n  }\n\n  read<T, M = undefined>(snapshotId: string, queryKey: string): PageSnapshot<T, M> {\n    const entry = this.#byId.get(snapshotId);\n    if (entry?.queryKey !== queryKey) throw invalidCursor();\n    return { items: entry.items as readonly T[], metadata: entry.metadata as M };\n  }\n\n  clear(): void {\n    this.#byId.clear();\n  }\n}\n"]}
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/core/store.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ContentBlock } from '@modelcontextprotocol/server';\n\nimport { randomUUID } from 'node:crypto';\n\nimport { ErrorCode, FsError } from './errors.ts';\nimport { MIB } from './util.ts';\n\n// ─── TTL + LRU map ───────────────────────────────────────────────────────────\n\n/**\n * A bounded, expiring map. `Map` keeps insertion order and a read re-inserts,\n * so the first key is always the least recently used one. Entries carry an\n * optional weight so a byte budget can be enforced next to the entry cap.\n */\nclass TtlLru<V> {\n  readonly #byKey = new Map<string, { value: V; expiresAt: number; weight: number }>();\n  readonly #maxEntries: number;\n  readonly #maxWeight: number;\n  readonly #ttlMs: number;\n  #weight = 0;\n\n  constructor(opts: { maxEntries: number; ttlMs: number; maxWeight?: number }) {\n    this.#maxEntries = opts.maxEntries;\n    this.#maxWeight = opts.maxWeight ?? Number.POSITIVE_INFINITY;\n    this.#ttlMs = opts.ttlMs;\n  }\n\n  /** Drop every expired entry; true when at least one went. */\n  prune(): boolean {\n    const now = Date.now();\n    const before = this.#byKey.size;\n    for (const [key, entry] of this.#byKey) {\n      if (entry.expiresAt <= now) this.delete(key);\n    }\n    return this.#byKey.size !== before;\n  }\n\n  /** The live value, bumped to most recently used; `undefined` when missing or expired. */\n  get(key: string): V | undefined {\n    const entry = this.#byKey.get(key);\n    if (!entry) return undefined;\n    if (entry.expiresAt <= Date.now()) {\n      this.delete(key);\n      return undefined;\n    }\n    this.#byKey.delete(key);\n    this.#byKey.set(key, entry);\n    return entry.value;\n  }\n\n  /** Insert (pruning expired first) and evict least recently used entries past either cap. */\n  set(key: string, value: V, weight = 0): void {\n    this.prune();\n    this.delete(key);\n    this.#byKey.set(key, { value, expiresAt: Date.now() + this.#ttlMs, weight });\n    this.#weight += weight;\n    while (\n      this.#byKey.size > 0 &&\n      (this.#byKey.size > this.#maxEntries || this.#weight > this.#maxWeight)\n    ) {\n      const oldest = this.#byKey.keys().next();\n      if (oldest.done) break;\n      this.delete(oldest.value);\n    }\n  }\n\n  delete(key: string): void {\n    const entry = this.#byKey.get(key);\n    if (!entry) return;\n    this.#weight -= entry.weight;\n    this.#byKey.delete(key);\n  }\n\n  /** Live keys, least recently used first. Prunes expired entries first. */\n  keys(): string[] {\n    this.prune();\n    return [...this.#byKey.keys()];\n  }\n\n  clear(): void {\n    this.#byKey.clear();\n    this.#weight = 0;\n  }\n}\n\n// ─── Resource store: externalized tool results ───────────────────────────────\n\ninterface ResourceEntry {\n  uri: string;\n  name: string;\n  mimeType: string;\n  size: number;\n  createdAt: string;\n  expiresAt: string;\n  text: string;\n}\n\nconst MAX_ENTRIES = 64;\nconst MAX_TOTAL_BYTES = 25 * MIB;\nconst MAX_ENTRY_BYTES = 10 * MIB;\nconst ENTRY_TTL_MS = 60 * 1000;\n\nexport class ResourceStore {\n  readonly #entries = new TtlLru<ResourceEntry>({\n    maxEntries: MAX_ENTRIES,\n    maxWeight: MAX_TOTAL_BYTES,\n    ttlMs: ENTRY_TTL_MS,\n  });\n  readonly #onListChanged: (() => void) | undefined;\n\n  constructor(onListChanged?: () => void) {\n    this.#onListChanged = onListChanged;\n  }\n\n  getEntry(uri: string): ResourceEntry {\n    const entry = this.#entries.get(uri);\n    if (entry) return entry;\n    // Not found and expired share a remedy; only the wording differs, and an\n    // expiry seen here changed the list a client may hold.\n    if (this.#entries.prune()) this.#onListChanged?.();\n    throw new FsError(\n      ErrorCode.NOT_FOUND,\n      `Resource not found: ${uri}. Re-run the tool to regenerate.`,\n    );\n  }\n\n  putText(params: { name: string; mimeType?: string; text: string }): ResourceEntry {\n    const entryBytes = Buffer.byteLength(params.text, 'utf8');\n    if (entryBytes > MAX_ENTRY_BYTES) {\n      if (this.#entries.prune()) this.#onListChanged?.();\n      throw new FsError(ErrorCode.TOO_LARGE, `Resource too large to cache (${entryBytes} bytes).`);\n    }\n    const now = Date.now();\n    const entry: ResourceEntry = {\n      uri: `filesystem-mcp://result/${randomUUID()}`,\n      name: params.name,\n      mimeType: params.mimeType ?? 'text/plain',\n      size: entryBytes,\n      createdAt: new Date(now).toISOString(),\n      expiresAt: new Date(now + ENTRY_TTL_MS).toISOString(),\n      text: params.text,\n    };\n    this.#entries.set(entry.uri, entry, entryBytes);\n    this.#onListChanged?.();\n    return entry;\n  }\n\n  /**\n   * Live URIs, oldest first. Deliberately silent about the prune it runs:\n   * this is the read path `resources/list` runs through, and the caller is\n   * already receiving the post-prune list.\n   */\n  keys(): string[] {\n    return this.#entries.keys();\n  }\n}\n\nexport interface JsonResourceResult {\n  entry: {\n    uri: string;\n    size: number;\n    mimeType: string;\n    expiresAt: string;\n  };\n  link: ContentBlock;\n}\n\n/**\n * Owner of the externalize-a-payload rule: a tool whose inline response is\n * truncated publishes the full value to the resource store as pretty-printed\n * JSON and hands back the URI to reach it by, plus the link block that offers\n * it to the user.\n */\nexport function putJsonResource(\n  store: ResourceStore,\n  name: string,\n  // `Record<string, unknown> | readonly unknown[]`, not `unknown` or `object`:\n  // JSON.stringify returns undefined for undefined and for functions, and `null`\n  // is excluded so non-string payloads cannot enter the store's text entry.\n  value: Record<string, unknown> | readonly unknown[],\n): JsonResourceResult {\n  const entry = store.putText({\n    name,\n    mimeType: 'application/json',\n    text: JSON.stringify(value, null, 2),\n  });\n\n  return {\n    entry: {\n      uri: entry.uri,\n      size: entry.size,\n      mimeType: entry.mimeType,\n      expiresAt: entry.expiresAt,\n    },\n    link: {\n      type: 'resource_link',\n      uri: entry.uri,\n      name: entry.name,\n      description: `Cached tool result; expires ${entry.expiresAt}`,\n      mimeType: entry.mimeType,\n      size: entry.size,\n      annotations: { audience: ['user'], lastModified: entry.createdAt },\n    },\n  };\n}\n\n// ─── Page snapshots: paginated result sets ───────────────────────────────────\n\nexport interface PageSnapshot<T = unknown, M = unknown> {\n  readonly items: readonly T[];\n  readonly metadata: M;\n}\n\n/**\n * The one cursor rejection: a cursor whose snapshot expired, was evicted, was\n * already consumed past its end, or belongs to a different query. Every case\n * has the same remedy, so they share one message.\n */\nexport function invalidCursor(): FsError {\n  return new FsError(\n    ErrorCode.INVALID_INPUT,\n    'Invalid cursor. Request the first page without a cursor.',\n  );\n}\n\nconst MAX_SNAPSHOTS = 32;\n\n/**\n * Short-lived snapshots of a completed query's full result set, so later pages\n * slice a stored array instead of re-scanning and re-sorting the filesystem.\n *\n * ponytail: bounded by snapshot count and TTL, not by bytes — MAX_SNAPSHOTS x\n * 20,000 `list` entries or MAX_SNAPSHOTS x 10,000 `search_text` matches, each\n * match retaining up to 20 more line strings at `context: 10`, order of a few\n * hundred MB held for 60s, and the HTTP leg shares one store so any caller can\n * drive it. If that shows up as memory pressure, pass a byte weight to `set`\n * the way `ResourceStore` does.\n */\nexport class PageSnapshotStore {\n  readonly #byId = new TtlLru<PageSnapshot & { queryKey: string }>({\n    maxEntries: MAX_SNAPSHOTS,\n    ttlMs: ENTRY_TTL_MS,\n  });\n\n  create(params: { queryKey: string; items: readonly unknown[]; metadata?: unknown }): string {\n    const snapshotId = randomUUID();\n    this.#byId.set(snapshotId, {\n      queryKey: params.queryKey,\n      items: params.items,\n      metadata: params.metadata,\n    });\n    return snapshotId;\n  }\n\n  read<T, M = undefined>(snapshotId: string, queryKey: string): PageSnapshot<T, M> {\n    const entry = this.#byId.get(snapshotId);\n    if (entry?.queryKey !== queryKey) throw invalidCursor();\n    return { items: entry.items as readonly T[], metadata: entry.metadata as M };\n  }\n\n  clear(): void {\n    this.#byId.clear();\n  }\n}\n"]}

package/dist/core/util.d.ts

@@ -17,6 +17,23 @@ export declare const escapeRegExp: (input: string) => string;
 export declare const PARALLEL_CONCURRENCY: number;
 export declare const ROOTS_TIMEOUT_MS = 5000;
 export declare function getMaxTextFileSize(): number;
+/**
+ * Upper bound, in bytes, on one inbound JSON-RPC message on either transport.
+ * Derived from the file-size limit so that a schema-valid `create` — whose
+ * combined content is capped at getMaxTextFileSize() (create.ts) in UTF-16
+ * units — still fits after JSON encoding. Per unit the schema counted, the
+ * wire carries at most three bytes for well-formed text: a BMP character is
+ * up to three UTF-8 bytes, an escaped ASCII character (newline, quote,
+ * backslash, tab) is two, a surrogate pair is four bytes for two units. Hence
+ * 3× the content, plus 1 MiB for the envelope, paths and sibling arguments.
+ * Not covered, deliberately: C0 control characters and lone surrogates
+ * (JSON-escaped to six bytes each) — the read tools already refuse such
+ * content as binary, and a caller sending it only loses its own connection.
+ * Past this bound HTTP answers 413 and stdio closes the connection (the
+ * SDK's ReadBuffer contract), so it is also the number the instructions
+ * resource and --print-config report.
+ */
+export declare function getMaxInboundMessageBytes(): number;
 /** Combined byte budget for one batched `read`. */
 export declare const READ_MANY_MAX_TOTAL_BYTES: number;
 /** Default line chunk size for read continuation when no explicit range was given. */

package/dist/core/util.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../../src/core/util.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,GAAG,QAAa,CAAC;AAE9B,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,GACV,MAAM,CAER;AA6BD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAKhE;AA6BD,qEAAqE;AACrE,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAS1D;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MACgD,CAAC;AAE/F,eAAO,MAAM,oBAAoB,QAAoD,CAAC;AAEtF,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,wBAAgB,kBAAkB,IAAI,MAAM,CAQ3C;AAED,mDAAmD;AACnD,eAAO,MAAM,yBAAyB,QAAY,CAAC;AAEnD,sFAAsF;AACtF,eAAO,MAAM,+BAA+B,MAAM,CAAC;AAEnD,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C,eAAO,MAAM,cAAc,KAAK,CAAC;AACjC,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC,eAAO,MAAM,gBAAgB,QAAQ,CAAC;AAEtC,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AACxC,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAC1C,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,eAAO,MAAM,8BAA8B,MAAM,CAAC"}
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../../src/core/util.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,GAAG,QAAa,CAAC;AAE9B,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,GACV,MAAM,CAER;AA6BD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAKhE;AA6BD,qEAAqE;AACrE,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAS1D;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MACgD,CAAC;AAE/F,eAAO,MAAM,oBAAoB,QAAoD,CAAC;AAEtF,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,wBAAgB,kBAAkB,IAAI,MAAM,CAQ3C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AACD,mDAAmD;AACnD,eAAO,MAAM,yBAAyB,QAAY,CAAC;AAEnD,sFAAsF;AACtF,eAAO,MAAM,+BAA+B,MAAM,CAAC;AAEnD,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C,eAAO,MAAM,cAAc,KAAK,CAAC;AACjC,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC,eAAO,MAAM,gBAAgB,QAAQ,CAAC;AAEtC,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AACxC,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAC1C,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,eAAO,MAAM,8BAA8B,MAAM,CAAC"}

package/dist/core/util.js

@@ -83,6 +83,25 @@ export const ROOTS_TIMEOUT_MS = 5000;
 export function getMaxTextFileSize() {
     return parseIntSetting('FS_MAX_FILE_SIZE', cli.maxFileSize ?? process.env['FS_MAX_FILE_SIZE'], 10 * MIB, MIB, 100 * MIB);
 }
+/**
+ * Upper bound, in bytes, on one inbound JSON-RPC message on either transport.
+ * Derived from the file-size limit so that a schema-valid `create` — whose
+ * combined content is capped at getMaxTextFileSize() (create.ts) in UTF-16
+ * units — still fits after JSON encoding. Per unit the schema counted, the
+ * wire carries at most three bytes for well-formed text: a BMP character is
+ * up to three UTF-8 bytes, an escaped ASCII character (newline, quote,
+ * backslash, tab) is two, a surrogate pair is four bytes for two units. Hence
+ * 3× the content, plus 1 MiB for the envelope, paths and sibling arguments.
+ * Not covered, deliberately: C0 control characters and lone surrogates
+ * (JSON-escaped to six bytes each) — the read tools already refuse such
+ * content as binary, and a caller sending it only loses its own connection.
+ * Past this bound HTTP answers 413 and stdio closes the connection (the
+ * SDK's ReadBuffer contract), so it is also the number the instructions
+ * resource and --print-config report.
+ */
+export function getMaxInboundMessageBytes() {
+    return 3 * getMaxTextFileSize() + MIB;
+}
 /** Combined byte budget for one batched `read`. */
 export const READ_MANY_MAX_TOTAL_BYTES = 512 * KIB;
 /** Default line chunk size for read continuation when no explicit range was given. */

package/dist/core/util.js.map

@@ -1 +1 @@
-{"version":3,"file":"util.js","sourceRoot":"","sources":["../../src/core/util.ts"],"names":[],"mappings":"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","sourcesContent":["import { availableParallelism } from 'node:os';\n\nimport { cli } from './config.ts';\nimport { warnInvalidSetting } from './path-utils.ts';\n\nconst KIB = 1024;\nexport const MIB = 1024 * KIB;\n\nexport function parseEnvInt(\n  envVar: string,\n  defaultValue: number,\n  min: number,\n  max: number,\n): number {\n  return parseIntSetting(envVar, process.env[envVar], defaultValue, min, max);\n}\n\n/** Validate a raw integer setting (env var or CLI override) with a logged fallback. */\nfunction parseIntSetting(\n  name: string,\n  value: string | undefined,\n  defaultValue: number,\n  min: number,\n  max: number,\n): number {\n  if (!value) {\n    return defaultValue;\n  }\n\n  const trimmed = value.trim();\n  const parsed = Number(trimmed);\n  if (\n    trimmed === '' ||\n    Number.isNaN(parsed) ||\n    !Number.isInteger(parsed) ||\n    parsed < min ||\n    parsed > max\n  ) {\n    warnInvalidSetting(name, value, `${String(min)}-${String(max)}`, defaultValue);\n    return defaultValue;\n  }\n  return parsed;\n}\n\n/**\n * Split a comma-separated config value into trimmed, non-empty entries. Empty\n * entries are dropped so \",\" or \" \" reads as unset rather than as a list of\n * blanks. Every comma-separated env var this server accepts parses through\n * here, so they all agree on what \"configured\" means.\n */\nexport function splitCsvList(value: string | undefined): string[] {\n  return (value ?? '')\n    .split(',')\n    .map((entry) => entry.trim())\n    .filter(Boolean);\n}\n\nconst REGEXP_SYNTAX = /[\\\\^$.*+?()[\\]{}|/]/;\nconst REGEXP_OTHER_PUNCTUATORS = /[,\\-=<>#&!%:;@~'`\"]/;\nconst REGEXP_CONTROL_ESCAPES: Readonly<Record<string, string>> = {\n  '\\t': 't',\n  '\\n': 'n',\n  '\\v': 'v',\n  '\\f': 'f',\n  '\\r': 'r',\n};\n\nconst hexEscape = (code: number, width: 2 | 4): string =>\n  `\\\\${width === 2 ? 'x' : 'u'}${code.toString(16).padStart(width, '0')}`;\n\nfunction encodeForRegExpEscape(ch: string): string {\n  if (REGEXP_SYNTAX.test(ch)) return `\\\\${ch}`;\n  const control = REGEXP_CONTROL_ESCAPES[ch];\n  if (control !== undefined) return `\\\\${control}`;\n  const code = ch.codePointAt(0) ?? 0;\n  const loneSurrogate = ch.length === 1 && code >= 0xd800 && code <= 0xdfff;\n  if (!REGEXP_OTHER_PUNCTUATORS.test(ch) && !/\\s/.test(ch) && !loneSurrogate) return ch;\n  if (code <= 0xff) return hexEscape(code, 2);\n  return ch\n    .split('')\n    .map((unit) => hexEscape(unit.charCodeAt(0), 4))\n    .join('');\n}\n\n/** The TC39 `RegExp.escape` algorithm, for runtimes that lack it. */\nexport function escapeRegExpFallback(input: string): string {\n  let out = '';\n  for (const ch of input) {\n    out +=\n      out === '' && /[0-9A-Za-z]/.test(ch)\n        ? hexEscape(ch.charCodeAt(0), 2)\n        : encodeForRegExpEscape(ch);\n  }\n  return out;\n}\n\n/**\n * `RegExp.escape` shipped in Node 24. Older runtimes still load the published\n * package (npm only warns on `engines`), so fall back rather than crash.\n */\nexport const escapeRegExp: (input: string) => string =\n  typeof RegExp.escape === 'function' ? (input) => RegExp.escape(input) : escapeRegExpFallback;\n\nexport const PARALLEL_CONCURRENCY = Math.min(Math.max(availableParallelism(), 4), 32);\n\nexport const ROOTS_TIMEOUT_MS = 5000;\n\nexport function getMaxTextFileSize(): number {\n  return parseIntSetting(\n    'FS_MAX_FILE_SIZE',\n    cli.maxFileSize ?? process.env['FS_MAX_FILE_SIZE'],\n    10 * MIB,\n    MIB,\n    100 * MIB,\n  );\n}\n\n/** Combined byte budget for one batched `read`. */\nexport const READ_MANY_MAX_TOTAL_BYTES = 512 * KIB;\n\n/** Default line chunk size for read continuation when no explicit range was given. */\nexport const DEFAULT_CONTINUATION_CHUNK_SIZE = 200;\n\nexport const DEFAULT_SEARCH_TIMEOUT_MS = 5000;\n\nexport const MAX_TREE_DEPTH = 50;\nexport const DEFAULT_TREE_ENTRIES = 1000;\n\nexport const MAX_LIST_ENTRIES = 20000;\n\nexport const MAX_SEARCH_RESULTS = 10000;\nexport const DEFAULT_SEARCH_RESULTS = 100;\nexport const MAX_SEARCH_DEPTH = 100;\n\nexport const DEFAULT_SEARCH_CONTENT_RESULTS = 500;\n"]}
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../../src/core/util.ts"],"names":[],"mappings":"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","sourcesContent":["import { availableParallelism } from 'node:os';\n\nimport { cli } from './config.ts';\nimport { warnInvalidSetting } from './path-utils.ts';\n\nconst KIB = 1024;\nexport const MIB = 1024 * KIB;\n\nexport function parseEnvInt(\n  envVar: string,\n  defaultValue: number,\n  min: number,\n  max: number,\n): number {\n  return parseIntSetting(envVar, process.env[envVar], defaultValue, min, max);\n}\n\n/** Validate a raw integer setting (env var or CLI override) with a logged fallback. */\nfunction parseIntSetting(\n  name: string,\n  value: string | undefined,\n  defaultValue: number,\n  min: number,\n  max: number,\n): number {\n  if (!value) {\n    return defaultValue;\n  }\n\n  const trimmed = value.trim();\n  const parsed = Number(trimmed);\n  if (\n    trimmed === '' ||\n    Number.isNaN(parsed) ||\n    !Number.isInteger(parsed) ||\n    parsed < min ||\n    parsed > max\n  ) {\n    warnInvalidSetting(name, value, `${String(min)}-${String(max)}`, defaultValue);\n    return defaultValue;\n  }\n  return parsed;\n}\n\n/**\n * Split a comma-separated config value into trimmed, non-empty entries. Empty\n * entries are dropped so \",\" or \" \" reads as unset rather than as a list of\n * blanks. Every comma-separated env var this server accepts parses through\n * here, so they all agree on what \"configured\" means.\n */\nexport function splitCsvList(value: string | undefined): string[] {\n  return (value ?? '')\n    .split(',')\n    .map((entry) => entry.trim())\n    .filter(Boolean);\n}\n\nconst REGEXP_SYNTAX = /[\\\\^$.*+?()[\\]{}|/]/;\nconst REGEXP_OTHER_PUNCTUATORS = /[,\\-=<>#&!%:;@~'`\"]/;\nconst REGEXP_CONTROL_ESCAPES: Readonly<Record<string, string>> = {\n  '\\t': 't',\n  '\\n': 'n',\n  '\\v': 'v',\n  '\\f': 'f',\n  '\\r': 'r',\n};\n\nconst hexEscape = (code: number, width: 2 | 4): string =>\n  `\\\\${width === 2 ? 'x' : 'u'}${code.toString(16).padStart(width, '0')}`;\n\nfunction encodeForRegExpEscape(ch: string): string {\n  if (REGEXP_SYNTAX.test(ch)) return `\\\\${ch}`;\n  const control = REGEXP_CONTROL_ESCAPES[ch];\n  if (control !== undefined) return `\\\\${control}`;\n  const code = ch.codePointAt(0) ?? 0;\n  const loneSurrogate = ch.length === 1 && code >= 0xd800 && code <= 0xdfff;\n  if (!REGEXP_OTHER_PUNCTUATORS.test(ch) && !/\\s/.test(ch) && !loneSurrogate) return ch;\n  if (code <= 0xff) return hexEscape(code, 2);\n  return ch\n    .split('')\n    .map((unit) => hexEscape(unit.charCodeAt(0), 4))\n    .join('');\n}\n\n/** The TC39 `RegExp.escape` algorithm, for runtimes that lack it. */\nexport function escapeRegExpFallback(input: string): string {\n  let out = '';\n  for (const ch of input) {\n    out +=\n      out === '' && /[0-9A-Za-z]/.test(ch)\n        ? hexEscape(ch.charCodeAt(0), 2)\n        : encodeForRegExpEscape(ch);\n  }\n  return out;\n}\n\n/**\n * `RegExp.escape` shipped in Node 24. Older runtimes still load the published\n * package (npm only warns on `engines`), so fall back rather than crash.\n */\nexport const escapeRegExp: (input: string) => string =\n  typeof RegExp.escape === 'function' ? (input) => RegExp.escape(input) : escapeRegExpFallback;\n\nexport const PARALLEL_CONCURRENCY = Math.min(Math.max(availableParallelism(), 4), 32);\n\nexport const ROOTS_TIMEOUT_MS = 5000;\n\nexport function getMaxTextFileSize(): number {\n  return parseIntSetting(\n    'FS_MAX_FILE_SIZE',\n    cli.maxFileSize ?? process.env['FS_MAX_FILE_SIZE'],\n    10 * MIB,\n    MIB,\n    100 * MIB,\n  );\n}\n\n/**\n * Upper bound, in bytes, on one inbound JSON-RPC message on either transport.\n * Derived from the file-size limit so that a schema-valid `create` — whose\n * combined content is capped at getMaxTextFileSize() (create.ts) in UTF-16\n * units — still fits after JSON encoding. Per unit the schema counted, the\n * wire carries at most three bytes for well-formed text: a BMP character is\n * up to three UTF-8 bytes, an escaped ASCII character (newline, quote,\n * backslash, tab) is two, a surrogate pair is four bytes for two units. Hence\n * 3× the content, plus 1 MiB for the envelope, paths and sibling arguments.\n * Not covered, deliberately: C0 control characters and lone surrogates\n * (JSON-escaped to six bytes each) — the read tools already refuse such\n * content as binary, and a caller sending it only loses its own connection.\n * Past this bound HTTP answers 413 and stdio closes the connection (the\n * SDK's ReadBuffer contract), so it is also the number the instructions\n * resource and --print-config report.\n */\nexport function getMaxInboundMessageBytes(): number {\n  return 3 * getMaxTextFileSize() + MIB;\n}\n/** Combined byte budget for one batched `read`. */\nexport const READ_MANY_MAX_TOTAL_BYTES = 512 * KIB;\n\n/** Default line chunk size for read continuation when no explicit range was given. */\nexport const DEFAULT_CONTINUATION_CHUNK_SIZE = 200;\n\nexport const DEFAULT_SEARCH_TIMEOUT_MS = 5000;\n\nexport const MAX_TREE_DEPTH = 50;\nexport const DEFAULT_TREE_ENTRIES = 1000;\n\nexport const MAX_LIST_ENTRIES = 20000;\n\nexport const MAX_SEARCH_RESULTS = 10000;\nexport const DEFAULT_SEARCH_RESULTS = 100;\nexport const MAX_SEARCH_DEPTH = 100;\n\nexport const DEFAULT_SEARCH_CONTENT_RESULTS = 500;\n"]}

package/dist/instructions.js

@@ -47,7 +47,7 @@ export function buildSectionsRecord(readOnly) {
             `allowed_roots: Startup roots come from CLI paths, FS_ALLOWED_DIRS, or --allow-cwd; accepted modern grants are additive. Call ${LIST_ROOTS.name} to read the current set.`,
             'legacy_roots: Legacy clients may additionally seed roots through the deprecated roots/list flow.',
             'sensitive_paths: Sensitive file paths (.env, *.pem, SSH private keys such as *id_rsa* and *id_ed25519*, .netrc, .git-credentials) are denied by default.',
-            `enforced_limits: max file size ${maxFileMb} MB, file search cap ${MAX_SEARCH_RESULTS} results, content search scans up to ${MAX_SEARCH_RESULTS} matches, paged by maxResults (default ${DEFAULT_SEARCH_CONTENT_RESULTS}).`,
+            `enforced_limits: max file size ${maxFileMb} MB (also the combined content cap of one create call), file search cap ${MAX_SEARCH_RESULTS} results, content search scans up to ${MAX_SEARCH_RESULTS} matches, paged by maxResults (default ${DEFAULT_SEARCH_CONTENT_RESULTS}).`,
             'ephemeral_results: When a result carries a resource_link or a resourceUri (in structuredContent or _meta), call resources/read immediately — cached results are ephemeral and expire after ~60 seconds, eviction, or restart.',
             'pagination: nextCursor appears in the result text and in _meta, backed by a snapshot on the same ~60s clock. Send the printed Next page call as-is (the original arguments plus cursor); if a cursor is rejected, start again without one. resourceUri appears on the first page only.',
             '```',

package/dist/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,8BAA8B,EAC9B,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,UAAU,EACV,IAAI,EACJ,UAAU,EACV,mBAAmB,EACnB,IAAI,EACJ,WAAW,EACX,IAAI,GACL,MAAM,kBAAkB,CAAC;AAE1B,SAAS,kBAAkB,CAAC,QAAiB;IAC3C,MAAM,IAAI,GAAyB;QACjC,CAAC,UAAU,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;QAC3D,CAAC,SAAS,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;QAC1C,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;KACtB,CAAC;IAEF,4EAA4E;IAC5E,4EAA4E;IAC5E,iCAAiC;IACjC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAAC;IACjD,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,KAAK,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC3E,OAAO,WAAW,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC;AAClD,CAAC;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAG,yBAAyB,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAC/B,6DAA6D;IAC7D,kHAAkH,CAAC;AAErH,MAAM,UAAU,mBAAmB,CAAC,QAAiB;IACnD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,kBAAkB,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC;IACjE,OAAO;QACL,UAAU,EAAE;YACV,aAAa;YACb,KAAK;YACL,gBAAgB,UAAU,CAAC,IAAI,0EAA0E;YACzG,qKAAqK;YACrK,wCAAwC,IAAI,CAAC,IAAI,OAAO,UAAU,CAAC,IAAI,uBAAuB;YAC9F,KAAK;SACN,CAAC,IAAI,CAAC,IAAI,CAAC;QACZ,cAAc,EAAE;YACd,iBAAiB;YACjB,kBAAkB,CAAC,QAAQ,CAAC;YAC5B,EAAE;YACF,kEAAkE;SACnE,CAAC,IAAI,CAAC,IAAI,CAAC;QACZ,WAAW,EAAE;YACX,cAAc;YACd,KAAK;YACL,gIAAgI,UAAU,CAAC,IAAI,2BAA2B;YAC1K,kGAAkG;YAClG,0JAA0J;YAC1J,kCAAkC,SAAS,wBAAwB,kBAAkB,wCAAwC,kBAAkB,0CAA0C,8BAA8B,IAAI;YAC3N,+NAA+N;YAC/N,wRAAwR;YACxR,KAAK;SACN,CAAC,IAAI,CAAC,IAAI,CAAC;QACZ,cAAc,EAAE;YACd,iBAAiB;YACjB,KAAK;YACL,sBAAsB,UAAU,CAAC,IAAI,oFAAoF;YACzH,kBAAkB,IAAI,CAAC,IAAI,OAAO,UAAU,CAAC,IAAI,sBAAsB;YACvE,kBAAkB,IAAI,CAAC,IAAI,sEAAsE;YACjG,mFAAmF;YACnF,uDAAuD;YACvD,KAAK;SACN,CAAC,IAAI,CAAC,IAAI,CAAC;KACb,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,QAAgC;IAC7D,OAAO,KAAK,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;AACvD,CAAC","sourcesContent":["import {\n  DEFAULT_SEARCH_CONTENT_RESULTS,\n  getMaxTextFileSize,\n  MAX_SEARCH_RESULTS,\n} from './core/util.ts';\nimport {\n  FIND_FILES,\n  LIST,\n  LIST_ROOTS,\n  MUTATING_TOOL_NAMES,\n  READ,\n  SEARCH_TEXT,\n  STAT,\n} from './tools/index.ts';\n\nfunction buildToolsOverview(readOnly: boolean): string {\n  const rows: [string, string[]][] = [\n    ['Navigate', [LIST_ROOTS.name, LIST.name, FIND_FILES.name]],\n    ['Inspect', [STAT.name, SEARCH_TEXT.name]],\n    ['Read', [READ.name]],\n  ];\n\n  // Under --read-only the mutating tools are never registered, so advertising\n  // them here would point the model at tools that are not there. Drop the row\n  // rather than emit an empty one.\n  if (!readOnly) {\n    rows.push(['Write', [...MUTATING_TOOL_NAMES]]);\n  }\n\n  const rowLines = rows.map(([cat, names]) => `${cat}: ${names.join(', ')}`);\n  return `\\`\\`\\`\\n${rowLines.join('\\n')}\\n\\`\\`\\``;\n}\n\nexport const INSTRUCTIONS_URI = 'internal://instructions';\n\n/**\n * The one statement of what this server is and how to approach it. The server's\n * `instructions`, the `get-help` prompt, and the instructions resource all\n * describe the same document, and three hand-maintained paraphrases of it drift\n * against each other and cost the client the same sentence three times.\n */\nexport const INSTRUCTIONS_SUMMARY =\n  'Navigation guide for filesystem-mcp tools and constraints. ' +\n  'Use list_roots to inspect configured or accepted roots, then list/find_files -> stat -> read. Never guess paths.';\n\nexport function buildSectionsRecord(readOnly: boolean): Record<string, string> {\n  const maxFileMb = Math.floor(getMaxTextFileSize() / 1024 / 1024);\n  return {\n    guidelines: [\n      'Guidelines:',\n      '```',\n      `root_access: ${LIST_ROOTS.name} lists configured or accepted roots; every other tool is scoped to them.`,\n      'modern_root_grants: Modern clients do not automatically send workspace roots. Call a tool with a concrete path and approve its grant when elicitation is available.',\n      `path_resolution: Confirm a path with ${LIST.name} or ${FIND_FILES.name} before acting on it.`,\n      '```',\n    ].join('\\n'),\n    tools_overview: [\n      'Tools Overview:',\n      buildToolsOverview(readOnly),\n      '',\n      'Full schemas, descriptions, and annotations are in `tools/list`.',\n    ].join('\\n'),\n    constraints: [\n      'Constraints:',\n      '```',\n      `allowed_roots: Startup roots come from CLI paths, FS_ALLOWED_DIRS, or --allow-cwd; accepted modern grants are additive. Call ${LIST_ROOTS.name} to read the current set.`,\n      'legacy_roots: Legacy clients may additionally seed roots through the deprecated roots/list flow.',\n      'sensitive_paths: Sensitive file paths (.env, *.pem, SSH private keys such as *id_rsa* and *id_ed25519*, .netrc, .git-credentials) are denied by default.',\n      `enforced_limits: max file size ${maxFileMb} MB, file search cap ${MAX_SEARCH_RESULTS} results, content search scans up to ${MAX_SEARCH_RESULTS} matches, paged by maxResults (default ${DEFAULT_SEARCH_CONTENT_RESULTS}).`,\n      'ephemeral_results: When a result carries a resource_link or a resourceUri (in structuredContent or _meta), call resources/read immediately — cached results are ephemeral and expire after ~60 seconds, eviction, or restart.',\n      'pagination: nextCursor appears in the result text and in _meta, backed by a snapshot on the same ~60s clock. Send the printed Next page call as-is (the original arguments plus cursor); if a cursor is rejected, start again without one. resourceUri appears on the first page only.',\n      '```',\n    ].join('\\n'),\n    error_recovery: [\n      'Error Recovery:',\n      '```',\n      `ACCESS_DENIED: Run ${LIST_ROOTS.name}; configure a missing startup root or retry a concrete path and approve the grant.`,\n      `NOT_FOUND: Run ${LIST.name} or ${FIND_FILES.name} to verify the path.`,\n      `TOO_LARGE: Use ${READ.name} with head/tail or startLine/endLine, or split across several calls.`,\n      'TIMEOUT: Narrow path or pattern, or lower maxDepth; maxResults only sizes a page.',\n      'INVALID_INPUT: Re-read the tool schema in tools/list.',\n      '```',\n    ].join('\\n'),\n  };\n}\n\nexport function renderSections(sections: Record<string, string>): string {\n  return `\\n${Object.values(sections).join('\\n\\n')}\\n`;\n}\n"]}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,8BAA8B,EAC9B,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,UAAU,EACV,IAAI,EACJ,UAAU,EACV,mBAAmB,EACnB,IAAI,EACJ,WAAW,EACX,IAAI,GACL,MAAM,kBAAkB,CAAC;AAE1B,SAAS,kBAAkB,CAAC,QAAiB;IAC3C,MAAM,IAAI,GAAyB;QACjC,CAAC,UAAU,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;QAC3D,CAAC,SAAS,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;QAC1C,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;KACtB,CAAC;IAEF,4EAA4E;IAC5E,4EAA4E;IAC5E,iCAAiC;IACjC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAAC;IACjD,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,KAAK,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC3E,OAAO,WAAW,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC;AAClD,CAAC;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAG,yBAAyB,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAC/B,6DAA6D;IAC7D,kHAAkH,CAAC;AAErH,MAAM,UAAU,mBAAmB,CAAC,QAAiB;IACnD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,kBAAkB,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC;IACjE,OAAO;QACL,UAAU,EAAE;YACV,aAAa;YACb,KAAK;YACL,gBAAgB,UAAU,CAAC,IAAI,0EAA0E;YACzG,qKAAqK;YACrK,wCAAwC,IAAI,CAAC,IAAI,OAAO,UAAU,CAAC,IAAI,uBAAuB;YAC9F,KAAK;SACN,CAAC,IAAI,CAAC,IAAI,CAAC;QACZ,cAAc,EAAE;YACd,iBAAiB;YACjB,kBAAkB,CAAC,QAAQ,CAAC;YAC5B,EAAE;YACF,kEAAkE;SACnE,CAAC,IAAI,CAAC,IAAI,CAAC;QACZ,WAAW,EAAE;YACX,cAAc;YACd,KAAK;YACL,gIAAgI,UAAU,CAAC,IAAI,2BAA2B;YAC1K,kGAAkG;YAClG,0JAA0J;YAC1J,kCAAkC,SAAS,2EAA2E,kBAAkB,wCAAwC,kBAAkB,0CAA0C,8BAA8B,IAAI;YAC9Q,+NAA+N;YAC/N,wRAAwR;YACxR,KAAK;SACN,CAAC,IAAI,CAAC,IAAI,CAAC;QACZ,cAAc,EAAE;YACd,iBAAiB;YACjB,KAAK;YACL,sBAAsB,UAAU,CAAC,IAAI,oFAAoF;YACzH,kBAAkB,IAAI,CAAC,IAAI,OAAO,UAAU,CAAC,IAAI,sBAAsB;YACvE,kBAAkB,IAAI,CAAC,IAAI,sEAAsE;YACjG,mFAAmF;YACnF,uDAAuD;YACvD,KAAK;SACN,CAAC,IAAI,CAAC,IAAI,CAAC;KACb,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,QAAgC;IAC7D,OAAO,KAAK,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;AACvD,CAAC","sourcesContent":["import {\n  DEFAULT_SEARCH_CONTENT_RESULTS,\n  getMaxTextFileSize,\n  MAX_SEARCH_RESULTS,\n} from './core/util.ts';\nimport {\n  FIND_FILES,\n  LIST,\n  LIST_ROOTS,\n  MUTATING_TOOL_NAMES,\n  READ,\n  SEARCH_TEXT,\n  STAT,\n} from './tools/index.ts';\n\nfunction buildToolsOverview(readOnly: boolean): string {\n  const rows: [string, string[]][] = [\n    ['Navigate', [LIST_ROOTS.name, LIST.name, FIND_FILES.name]],\n    ['Inspect', [STAT.name, SEARCH_TEXT.name]],\n    ['Read', [READ.name]],\n  ];\n\n  // Under --read-only the mutating tools are never registered, so advertising\n  // them here would point the model at tools that are not there. Drop the row\n  // rather than emit an empty one.\n  if (!readOnly) {\n    rows.push(['Write', [...MUTATING_TOOL_NAMES]]);\n  }\n\n  const rowLines = rows.map(([cat, names]) => `${cat}: ${names.join(', ')}`);\n  return `\\`\\`\\`\\n${rowLines.join('\\n')}\\n\\`\\`\\``;\n}\n\nexport const INSTRUCTIONS_URI = 'internal://instructions';\n\n/**\n * The one statement of what this server is and how to approach it. The server's\n * `instructions`, the `get-help` prompt, and the instructions resource all\n * describe the same document, and three hand-maintained paraphrases of it drift\n * against each other and cost the client the same sentence three times.\n */\nexport const INSTRUCTIONS_SUMMARY =\n  'Navigation guide for filesystem-mcp tools and constraints. ' +\n  'Use list_roots to inspect configured or accepted roots, then list/find_files -> stat -> read. Never guess paths.';\n\nexport function buildSectionsRecord(readOnly: boolean): Record<string, string> {\n  const maxFileMb = Math.floor(getMaxTextFileSize() / 1024 / 1024);\n  return {\n    guidelines: [\n      'Guidelines:',\n      '```',\n      `root_access: ${LIST_ROOTS.name} lists configured or accepted roots; every other tool is scoped to them.`,\n      'modern_root_grants: Modern clients do not automatically send workspace roots. Call a tool with a concrete path and approve its grant when elicitation is available.',\n      `path_resolution: Confirm a path with ${LIST.name} or ${FIND_FILES.name} before acting on it.`,\n      '```',\n    ].join('\\n'),\n    tools_overview: [\n      'Tools Overview:',\n      buildToolsOverview(readOnly),\n      '',\n      'Full schemas, descriptions, and annotations are in `tools/list`.',\n    ].join('\\n'),\n    constraints: [\n      'Constraints:',\n      '```',\n      `allowed_roots: Startup roots come from CLI paths, FS_ALLOWED_DIRS, or --allow-cwd; accepted modern grants are additive. Call ${LIST_ROOTS.name} to read the current set.`,\n      'legacy_roots: Legacy clients may additionally seed roots through the deprecated roots/list flow.',\n      'sensitive_paths: Sensitive file paths (.env, *.pem, SSH private keys such as *id_rsa* and *id_ed25519*, .netrc, .git-credentials) are denied by default.',\n      `enforced_limits: max file size ${maxFileMb} MB (also the combined content cap of one create call), file search cap ${MAX_SEARCH_RESULTS} results, content search scans up to ${MAX_SEARCH_RESULTS} matches, paged by maxResults (default ${DEFAULT_SEARCH_CONTENT_RESULTS}).`,\n      'ephemeral_results: When a result carries a resource_link or a resourceUri (in structuredContent or _meta), call resources/read immediately — cached results are ephemeral and expire after ~60 seconds, eviction, or restart.',\n      'pagination: nextCursor appears in the result text and in _meta, backed by a snapshot on the same ~60s clock. Send the printed Next page call as-is (the original arguments plus cursor); if a cursor is rejected, start again without one. resourceUri appears on the first page only.',\n      '```',\n    ].join('\\n'),\n    error_recovery: [\n      'Error Recovery:',\n      '```',\n      `ACCESS_DENIED: Run ${LIST_ROOTS.name}; configure a missing startup root or retry a concrete path and approve the grant.`,\n      `NOT_FOUND: Run ${LIST.name} or ${FIND_FILES.name} to verify the path.`,\n      `TOO_LARGE: Use ${READ.name} with head/tail or startLine/endLine, or split across several calls.`,\n      'TIMEOUT: Narrow path or pattern, or lower maxDepth; maxResults only sizes a page.',\n      'INVALID_INPUT: Re-read the tool schema in tools/list.',\n      '```',\n    ].join('\\n'),\n  };\n}\n\nexport function renderSections(sections: Record<string, string>): string {\n  return `\\n${Object.values(sections).join('\\n\\n')}\\n`;\n}\n"]}

package/dist/resources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,gCAAgC,EAChC,SAAS,EACT,kBAAkB,EAClB,QAAQ,EAER,IAAI,EACJ,aAAa,EACb,cAAc,EAGf,MAAM,8BAA8B,CAAC;AAoBtC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AAYpC,MAAM,WAAW,2BAA2B;IAC1C,aAAa,EAAE,aAAa,CAAC;IAC7B,SAAS,EAAE,SAAS,CAAC;IACrB,8FAA8F;IAC9F,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,qFAAqF;IACrF,GAAG,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B;;;;OAIG;IACH,UAAU,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;CACnC;AAED,KAAK,qBAAqB,GAAG,IAAI,CAAC,2BAA2B,EAAE,WAAW,GAAG,UAAU,CAAC,GAAG;IACzF,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B,CAAC;AAoBF,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,WAAW,CAAC,EAAE;QACZ,QAAQ,CAAC,EAAE,IAAI,EAAE,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,gEAAgE;IAChE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,gCAAgC,CAAA;KAAE,CAAC;IACtD,QAAQ,CAAC,IAAI,EAAE,CACb,GAAG,EAAE,GAAG,EACR,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,EAC5C,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,CAAC;IACtD,QAAQ,CAAC,SAAS,CAAC,EAAE,CACnB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,KAC1B,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,GAAG,OAAO,GAAG,SAAS,CAAC;IACxD,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,CACd,GAAG,EAAE,aAAa,KACf,OAAO,CAAC;QAAE,SAAS,EAAE,QAAQ,EAAE,CAAA;KAAE,CAAC,GAAG;QAAE,SAAS,EAAE,QAAQ,EAAE,CAAA;KAAE,CAAC;CACrE;AA4PD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,gBAAgB,EAAE,CAM7F;AA8DD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,qBAAqB,GAAG;IAAE,OAAO,IAAI,IAAI,CAAA;CAAE,CAoHlF"}
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,gCAAgC,EAChC,SAAS,EACT,kBAAkB,EAClB,QAAQ,EAER,IAAI,EACJ,aAAa,EACb,cAAc,EAGf,MAAM,8BAA8B,CAAC;AAoBtC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AAYpC,MAAM,WAAW,2BAA2B;IAC1C,aAAa,EAAE,aAAa,CAAC;IAC7B,SAAS,EAAE,SAAS,CAAC;IACrB,8FAA8F;IAC9F,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,qFAAqF;IACrF,GAAG,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B;;;;OAIG;IACH,UAAU,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;CACnC;AAED,KAAK,qBAAqB,GAAG,IAAI,CAAC,2BAA2B,EAAE,WAAW,GAAG,UAAU,CAAC,GAAG;IACzF,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B,CAAC;AAoBF,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,WAAW,CAAC,EAAE;QACZ,QAAQ,CAAC,EAAE,IAAI,EAAE,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,gEAAgE;IAChE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,gCAAgC,CAAA;KAAE,CAAC;IACtD,QAAQ,CAAC,IAAI,EAAE,CACb,GAAG,EAAE,GAAG,EACR,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,EAC5C,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,CAAC;IACtD,QAAQ,CAAC,SAAS,CAAC,EAAE,CACnB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,KAC1B,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,GAAG,OAAO,GAAG,SAAS,CAAC;IACxD,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,CACd,GAAG,EAAE,aAAa,KACf,OAAO,CAAC;QAAE,SAAS,EAAE,QAAQ,EAAE,CAAA;KAAE,CAAC,GAAG;QAAE,SAAS,EAAE,QAAQ,EAAE,CAAA;KAAE,CAAC;CACrE;AA+PD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,gBAAgB,EAAE,CAM7F;AA8DD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,qBAAqB,GAAG;IAAE,OAAO,IAAI,IAAI,CAAA;CAAE,CAoHlF"}

package/dist/resources.js

@@ -82,7 +82,8 @@ function createFilesystemResource(options) {
         // not enumerable. Listing each allowed root as a concrete resource
         // duplicated the template and grew resources/list linearly with roots;
         // `list_roots` owns root discovery.
-        async read(uri, _variables, _ctx) {
+        async read(uri, _variables, ctx) {
+            ctx.mcpReq.signal.throwIfAborted();
             // Decode via extractPath — the same decoder resources/subscribe uses — so
             // both consumers are symmetric with buildFileResourceUri's encoding. The
             // {+path} template variable arrives still percent-encoded, so validating
@@ -96,7 +97,7 @@ function createFilesystemResource(options) {
             }
             await options.pathGuard.validateExistingPath(rawPath);
             const fs = new GuardedFileSystem(options.pathGuard);
-            const readResult = await fs.readRaw(rawPath);
+            const readResult = await fs.readRaw(rawPath, { signal: ctx.mcpReq.signal });
             return {
                 contents: [
                     {
@@ -200,8 +201,10 @@ function createResultResource(options) {
                     resources.push({
                         uri: entry.uri,
                         name: entry.name,
+                        description: `Cached tool result; expires ${entry.expiresAt}`,
                         mimeType: entry.mimeType,
                         size: entry.size,
+                        annotations: { audience: ['assistant'], priority: 0.3, lastModified: entry.createdAt },
                     });
                 }
                 catch (err) {

package/dist/resources.js.map

@@ -1 +1 @@
-{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  CacheHint,\n  CompleteResourceTemplateCallback,\n  McpServer,\n  ReadResourceResult,\n  Resource,\n  ResourceUpdatedNotificationParams,\n  Role,\n  ServerContext,\n  ServerNotifier,\n  SubscribeRequestParams,\n  UnsubscribeRequestParams,\n} from '@modelcontextprotocol/server';\nimport {\n  ProtocolError,\n  ProtocolErrorCode,\n  ResourceNotFoundError,\n  ResourceTemplate,\n  UriTemplate,\n} from '@modelcontextprotocol/server';\n\nimport type { FsError } from './core/errors.ts';\nimport { ErrorCode, formatUnknownErrorMessage, isFsError } from './core/errors.ts';\nimport {\n  decodeFileUriPath,\n  encodeFileUriPath,\n  extractPath,\n  FILESYSTEM_FILE_URI_TEMPLATE,\n} from './core/file-uri.ts';\nimport { GuardedFileSystem } from './core/fs.ts';\nimport { Logger } from './core/observability.ts';\nimport { suggestPaths } from './core/path-completer.ts';\nimport type { PathGuard } from './core/path.ts';\nimport type { ResourceStore } from './core/store.ts';\nimport {\n  createWatcherRegistry,\n  MAX_WATCHERS,\n  type WatcherRegistry,\n} from './core/watcher-registry.ts';\nimport {\n  buildSectionsRecord,\n  INSTRUCTIONS_SUMMARY,\n  INSTRUCTIONS_URI,\n  renderSections,\n} from './instructions.ts';\n\n// ═══════════════════════════════════════════════════════════════\n// shared\n// ═══════════════════════════════════════════════════════════════\n\nexport interface ResourceRegistrationOptions {\n  resourceStore: ResourceStore;\n  pathGuard: PathGuard;\n  /** Mirrors the `--read-only` gate so the instructions match the tools actually registered. */\n  readOnly: boolean;\n  /**\n   * Shared file-watcher registry for the modern (per-request) HTTP leg. When set,\n   * the resource uses this handler-scoped registry instead of creating its own\n   * per-server one, so file-change watchers persist across requests and publish\n   * to the shared ServerEventBus. Omitted (per-server registry) on legacy/stdio.\n   */\n  watcherRegistry?: WatcherRegistry;\n  /** Modern-leg typed notification publisher. */\n  notifier?: ServerNotifier;\n  /** The protocol era this instance serves; omitted where the caller does not know. */\n  era?: 'legacy' | 'modern';\n  /**\n   * Scope for shared-content cache hints. 'private' when the endpoint is\n   * API-key gated, mirroring the list hints in server.ts — a shared cache must\n   * not store an authenticated response body. Defaults to 'public'.\n   */\n  cacheScope?: 'public' | 'private';\n}\n\ntype ResourceRegistrarDeps = Omit<ResourceRegistrationOptions, 'pathGuard' | 'readOnly'> & {\n  readonly server: McpServer;\n  readonly pathGuard: PathGuard;\n  readonly readOnly?: boolean;\n};\n\n/**\n * A filesystem failure that reads as not-found on the resource wire, for both\n * `resources/read` and `resources/subscribe`. ACCESS_DENIED folds in\n * deliberately: masking whether an out-of-root or denylisted path exists is the\n * security-correct answer, and the `FsError` message still carries the real\n * cause to the client.\n */\nfunction isNotFoundish(error: unknown): error is FsError {\n  return (\n    isFsError(error) &&\n    (error.code === ErrorCode.NOT_FOUND || error.code === ErrorCode.ACCESS_DENIED)\n  );\n}\n\n// ═══════════════════════════════════════════════════════════════\n// contract\n// ═══════════════════════════════════════════════════════════════\n\ninterface ResourceContract {\n  name: string;\n  title?: string;\n  description?: string;\n  mimeType?: string;\n  cacheHint?: CacheHint;\n  annotations?: {\n    audience?: Role[];\n    priority?: number;\n  };\n  /** A fixed, enumerable URI (e.g. internal://instructions)... */\n  uri?: string;\n  /** ...or a URI template, optionally with a completer for its variable. */\n  uriTemplate?: string;\n  complete?: { path: CompleteResourceTemplateCallback };\n  readonly read: (\n    uri: URL,\n    variables: Record<string, string | string[]>,\n    ctx: ServerContext,\n  ) => Promise<ReadResourceResult> | ReadResourceResult;\n  readonly subscribe?: (\n    uri: string,\n    notify: (uri: string) => void,\n  ) => Promise<boolean | undefined> | boolean | undefined;\n  readonly unsubscribe?: (uri: string) => void;\n  readonly destroy?: () => void;\n  readonly list?: (\n    ctx: ServerContext,\n  ) => Promise<{ resources: Resource[] }> | { resources: Resource[] };\n}\n\n/** The one contract with a live watcher behind it. */\ntype SubscribableContract = ResourceContract &\n  Required<Pick<ResourceContract, 'subscribe' | 'unsubscribe'>>;\n\n// ═══════════════════════════════════════════════════════════════\n// instructions\n// ═══════════════════════════════════════════════════════════════\n\nfunction createInstructionsResource(options: ResourceRegistrationOptions): ResourceContract {\n  const text = renderSections(buildSectionsRecord(options.readOnly));\n  return {\n    name: 'filesystem-mcp-instructions',\n    title: 'Server Instructions',\n    description: INSTRUCTIONS_SUMMARY,\n    mimeType: 'text/markdown',\n    uri: INSTRUCTIONS_URI,\n    annotations: { audience: ['assistant'], priority: 0.8 },\n    cacheHint: { cacheScope: options.cacheScope ?? 'public', ttlMs: 300_000 },\n    read(uri) {\n      return {\n        contents: [\n          {\n            uri: uri.href,\n            mimeType: 'text/markdown',\n            text,\n          },\n        ],\n      };\n    },\n  };\n}\n\n// ═══════════════════════════════════════════════════════════════\n// filesystem\n// ═══════════════════════════════════════════════════════════════\n\nfunction createFilesystemResource(options: ResourceRegistrationOptions): SubscribableContract {\n  const registry = options.watcherRegistry ?? createWatcherRegistry();\n  // Only the per-server (legacy/stdio) registry is owned by this resource and\n  // destroyed on dispose; the shared modern-leg registry is owned by the host\n  // and torn down at server shutdown.\n  const ownsRegistry = options.watcherRegistry === undefined;\n  // The URIs this connection holds a `resources/subscribe` lease for. The wire\n  // verb is per-URI and idempotent — a second subscribe is the same\n  // subscription, and one unsubscribe ends it — but the registry ref-counts\n  // leases (the HTTP listen leg needs that). Without this set a double\n  // subscribe took two leases that one unsubscribe could not release, and an\n  // unsubscribe for a URI never subscribed released a lease this connection\n  // never took, dropping a watcher some other holder still wanted.\n  const leasedUris = new Set<string>();\n  // Subscribes mid-acquire, keyed by URI. Two concurrent subscribes for the\n  // same URI must share one acquire: both passing the `leasedUris` check\n  // before either finished took two registry leases that the single set entry\n  // could release only once — on the shared modern registry that orphan lease\n  // pinned a watcher until process shutdown.\n  const inflight = new Map<string, Promise<boolean | undefined>>();\n\n  return {\n    name: 'filesystem-mcp-file',\n    title: 'Workspace File',\n    description: 'Read a file from the workspace. Subscribe to get updates when the file changes.',\n    uriTemplate: FILESYSTEM_FILE_URI_TEMPLATE,\n    annotations: { audience: ['assistant'], priority: 0.8 },\n    // Without this the SDK falls back to its conservative `{ ttlMs: 0,\n    // cacheScope: 'private' }`, making every file read uncacheable — and this\n    // is the one resource with a live invalidation channel, so TTL and the\n    // watcher compose exactly as the spec's caching section describes. The TTL\n    // stays short because a non-subscriber gets no invalidation signal at all.\n    cacheHint: { cacheScope: options.cacheScope ?? 'public', ttlMs: 5_000 },\n\n    // No `list`: the template registers with `list: undefined` — readable but\n    // not enumerable. Listing each allowed root as a concrete resource\n    // duplicated the template and grew resources/list linearly with roots;\n    // `list_roots` owns root discovery.\n\n    async read(uri, _variables, _ctx: ServerContext) {\n      // Decode via extractPath — the same decoder resources/subscribe uses — so\n      // both consumers are symmetric with buildFileResourceUri's encoding. The\n      // {+path} template variable arrives still percent-encoded, so validating\n      // it directly would treat \"c%3A/proj/a.ts\" as a literal relative path;\n      // no fallback to it here, or the two branches would validate different\n      // strings. extractPath only fails past the template match on undecodable\n      // percent-encoding, which is the caller's malformed URI.\n      const rawPath = extractPath(uri.href);\n      if (rawPath === undefined) {\n        throw new ProtocolError(\n          ProtocolErrorCode.InvalidParams,\n          'Malformed file URI: path is not valid percent-encoding',\n        );\n      }\n      await options.pathGuard.validateExistingPath(rawPath);\n      const fs = new GuardedFileSystem(options.pathGuard);\n      const readResult = await fs.readRaw(rawPath);\n\n      return {\n        contents: [\n          {\n            uri: uri.href,\n            mimeType: readResult.mimeType || 'application/octet-stream',\n            ...(readResult.isBinary\n              ? { blob: readResult.content.toString('base64') }\n              : { text: readResult.content.toString('utf-8') }),\n          },\n        ],\n      };\n    },\n\n    complete: {\n      // Both ends speak the `{+path}` form (see encodeFileUriPath), not raw OS\n      // paths: the partial arriving here is whatever this returned last, so the\n      // decode mirrors the encode. An undecodable partial is matched as typed.\n      path: async (value) => {\n        const suggestions = await suggestPaths(\n          options.pathGuard,\n          decodeFileUriPath(value) ?? value,\n        );\n        return suggestions.map(encodeFileUriPath);\n      },\n    },\n\n    subscribe(uri, notify) {\n      // Already subscribed on this connection: the watcher is live and the sink\n      // is registered, so this is a no-op success rather than a second lease.\n      if (leasedUris.has(uri)) return undefined;\n      // A subscribe for this URI is mid-acquire: share its outcome instead of\n      // taking a second lease the lease set cannot represent.\n      const pending = inflight.get(uri);\n      if (pending) return pending;\n\n      const acquire = async (): Promise<boolean | undefined> => {\n        const result = await registry.acquire(options.pathGuard, uri, notify, {\n          markSubscribe: true,\n        });\n        if (result.ok) {\n          leasedUris.add(uri);\n          return undefined;\n        }\n\n        if (result.reason === 'bad-uri') {\n          throw new ResourceNotFoundError(uri, `Cannot subscribe: not a filesystem URI`);\n        }\n        if (result.reason === 'invalid-path') {\n          const err = result.error;\n          if (isNotFoundish(err)) {\n            throw new ResourceNotFoundError(uri, `Cannot subscribe to ${uri}: ${err.message}`);\n          }\n          if (isFsError(err)) throw fsErrorToProtocolError(err);\n          Logger.warn(\n            `Unexpected error validating path for watcher ${uri}: ${formatUnknownErrorMessage(err)}`,\n          );\n          throw err;\n        }\n        // Unsubscribed (or the registry destroyed) mid-await: the caller already\n        // asked for this to stop, so there is nothing to reject.\n        if (result.reason === 'stale') return undefined;\n        // capped / attach-failed: `false` tells the handler to reject, since\n        // undefined would report success with no watcher attached.\n        return false;\n      };\n\n      const promise = acquire().finally(() => inflight.delete(uri));\n      inflight.set(uri, promise);\n      return promise;\n    },\n\n    unsubscribe(uri) {\n      // Only release a lease this connection actually took.\n      if (!leasedUris.delete(uri)) return;\n      registry.release(uri);\n    },\n\n    destroy() {\n      // Release what this connection still holds before the registry goes: on\n      // the shared (modern) registry nothing else would ever end these leases.\n      for (const uri of leasedUris) registry.release(uri);\n      leasedUris.clear();\n      if (ownsRegistry) registry.destroy();\n    },\n  };\n}\n\n// ═══════════════════════════════════════════════════════════════\n// result\n// ═══════════════════════════════════════════════════════════════\n\nfunction createResultResource(options: ResourceRegistrationOptions): ResourceContract {\n  return {\n    name: 'filesystem-mcp-result',\n    title: 'Cached Tool Result',\n    description:\n      'Ephemeral cached tool output. Listed via resources/list; entries expire after the cache TTL.',\n    mimeType: 'application/json',\n    uriTemplate: 'filesystem-mcp://result/{id}',\n    annotations: { audience: ['assistant'], priority: 0.3 },\n    cacheHint: { cacheScope: 'private', ttlMs: 60_000 },\n    list() {\n      const store = options.resourceStore;\n      const uris = store.keys(); // prunes expired first\n      const resources: Resource[] = [];\n      for (const uri of uris) {\n        try {\n          const entry = store.getEntry(uri);\n          resources.push({\n            uri: entry.uri,\n            name: entry.name,\n            mimeType: entry.mimeType,\n            size: entry.size,\n          });\n        } catch (err) {\n          // An entry may expire between keys() and getEntry; skip it.\n          if (isFsError(err) && err.code === ErrorCode.NOT_FOUND) continue;\n          throw err;\n        }\n      }\n      // Recent-first: keys() returns insertion order, so the newest is last.\n      resources.reverse();\n      return { resources };\n    },\n    read(uri, variables) {\n      const { id } = variables;\n      if (typeof id !== 'string' || id.length === 0) {\n        throw new ProtocolError(\n          ProtocolErrorCode.InvalidParams,\n          'Malformed result URI: missing {id}. Use the exact resourceUri returned by the tool.',\n        );\n      }\n\n      let entry;\n      try {\n        entry = options.resourceStore.getEntry(uri.toString());\n      } catch (err) {\n        if (isFsError(err) && err.code === ErrorCode.NOT_FOUND) {\n          throw new ResourceNotFoundError(\n            uri.toString(),\n            'Cached result not found or expired. Re-run the tool to regenerate.',\n          );\n        }\n        throw err;\n      }\n      return {\n        contents: [{ uri: entry.uri, mimeType: entry.mimeType, text: entry.text }],\n      };\n    },\n  };\n}\n\n// ═══════════════════════════════════════════════════════════════\n// export contracts\n// ═══════════════════════════════════════════════════════════════\n\nexport function getResourceContracts(options: ResourceRegistrationOptions): ResourceContract[] {\n  return [\n    createInstructionsResource(options),\n    createResultResource(options),\n    createFilesystemResource(options),\n  ];\n}\n\n// ═══════════════════════════════════════════════════════════════\n// registrar\n// ═══════════════════════════════════════════════════════════════\n\n/**\n * A caller-traceable FsError as the SDK's InvalidParams error. The Problem's\n * identity fields ride the SDK's error.data channel: `message` stays the\n * wire message, and code/path/suggestion give clients a machine-readable\n * view. Keyed by `code`, so it cannot collide with the\n * ResourceNotFoundError convention (data: { uri } and nothing else).\n */\nfunction fsErrorToProtocolError(error: FsError): ProtocolError {\n  const { code, path, suggestion } = error.problem;\n  return new ProtocolError(ProtocolErrorCode.InvalidParams, error.message, {\n    code,\n    ...(path !== undefined ? { path } : {}),\n    ...(suggestion !== undefined ? { suggestion } : {}),\n  });\n}\n\nfunction wrapRead(contract: ResourceContract) {\n  return async (uri: URL, variables: Record<string, string | string[]>, ctx: ServerContext) => {\n    try {\n      return await contract.read(uri, variables, ctx);\n    } catch (error) {\n      // The SDK brands ProtocolError with `static [Symbol.hasInstance]`, so this\n      // holds across separately bundled SDK copies and realms.\n      if (error instanceof ProtocolError) throw error;\n      // A missing or out-of-root path is a not-found, not a malformed request.\n      // The SDK puts ResourceNotFoundError on the wire as -32602 with\n      // `data.uri`, which is what clients match on; -32002 is the older code\n      // they also accept, and this SDK never emits it.\n      if (isNotFoundish(error)) {\n        throw new ResourceNotFoundError(uri.toString(), error.message);\n      }\n      // A remaining FsError (NOT_FILE, TOO_LARGE, ...) traces to the\n      // caller-supplied URI; anything else is a server-side failure and must\n      // not be blamed on the request.\n      if (isFsError(error)) throw fsErrorToProtocolError(error);\n      throw new ProtocolError(ProtocolErrorCode.InternalError, formatUnknownErrorMessage(error));\n    }\n  };\n}\n\n/**\n * Whether `contract` answers for `uri`, decided by the template matcher the SDK\n * dispatches `resources/read` with, so `resources/subscribe` and\n * `resources/read` agree on which resource owns a URI. Not\n * `checkResourceAllowed`: that is an RFC 8707 audience check comparing\n * `URL.origin`, which is the opaque `\"null\"` for every custom scheme, so it\n * matched `filesystem-mcp://result/…` — and any other scheme — to the file\n * template.\n */\nfunction owns(contract: ResourceContract, uri: string): boolean {\n  if (contract.uri !== undefined) return uri === contract.uri;\n  return (\n    contract.uriTemplate !== undefined && new UriTemplate(contract.uriTemplate).match(uri) !== null\n  );\n}\n\nexport function registerResources(deps: ResourceRegistrarDeps): { dispose(): void } {\n  const server = deps.server;\n  const options = { ...deps, readOnly: deps.readOnly ?? false };\n  const file = createFilesystemResource(options);\n  const resourceContracts = [\n    createInstructionsResource(options),\n    createResultResource(options),\n    file,\n  ];\n\n  for (const contract of resourceContracts) {\n    const config = {\n      ...(contract.title !== undefined ? { title: contract.title } : {}),\n      ...(contract.description !== undefined ? { description: contract.description } : {}),\n      ...(contract.mimeType !== undefined ? { mimeType: contract.mimeType } : {}),\n      ...(contract.annotations !== undefined ? { annotations: contract.annotations } : {}),\n      ...(contract.cacheHint !== undefined ? { cacheHint: contract.cacheHint } : {}),\n    };\n\n    if (contract.uriTemplate) {\n      const template = new ResourceTemplate(contract.uriTemplate, {\n        list: contract.list,\n        ...(contract.complete ? { complete: contract.complete } : {}),\n      });\n\n      server.registerResource(contract.name, template, config, wrapRead(contract));\n    } else if (contract.uri) {\n      server.registerResource(contract.name, contract.uri, config, (uri: URL, ctx: ServerContext) =>\n        wrapRead(contract)(uri, {}, ctx),\n      );\n    }\n  }\n\n  // `resources/subscribe`/`unsubscribe` are 2025-era-only verbs; a modern\n  // server answers `-32601 Method not found` for them, so registering these\n  // handlers on a modern-era instance would dispatch to code no request can\n  // reach. A legacy instance on the HTTP leg (the one built with a `notifier`)\n  // lives for one request: a subscription accepted there would take a watcher\n  // lease for an instance that is gone before the file changes. Leave the\n  // handlers off so the SDK refuses the verb, and no lease is taken. The\n  // predicate mirrors the capability gate in server.ts exactly, so the\n  // handler is registered if and only if `resources.subscribe` is advertised.\n  // sunset(SEP-2577): removal trigger in docs/adr/002-legacy-protocol-paths-sunset.md.\n  const legacyHttp = deps.era === 'legacy' && deps.notifier !== undefined;\n  if (deps.era !== 'modern' && !legacyHttp) {\n    server.server.assertCanSetRequestHandler('resources/subscribe');\n    server.server.assertCanSetRequestHandler('resources/unsubscribe');\n\n    // One stable callback for the whole registrar, NOT one per subscribe. The\n    // registry holds these in a Set keyed by identity, so a fresh closure per\n    // request made a second `resources/subscribe` for the same URI register a\n    // second sink: one file change then sent N notifications, and `unsubscribe`\n    // (which only ends a lease) removed none of them. Subscribe is per-URI on\n    // the wire, so the sink must be too — this makes it idempotent.\n    const notifyUpdated = (updatedUri: string): void => {\n      if (deps.notifier) {\n        deps.notifier.resourceUpdated(updatedUri);\n        return;\n      }\n      const updatePayload: ResourceUpdatedNotificationParams = { uri: updatedUri };\n      // A failed notify means the connection went away; nothing to recover.\n      void server.server.sendResourceUpdated(updatePayload).catch((err: unknown) => {\n        Logger.debug('resource update not delivered', {\n          uri: updatedUri,\n          error: formatUnknownErrorMessage(err),\n        });\n      });\n    };\n\n    server.server.setRequestHandler(\n      'resources/subscribe',\n      async (req: { params: SubscribeRequestParams }) => {\n        const { uri } = req.params;\n        if (!owns(file, uri)) {\n          // A resource that exists but has no watcher (the instructions text,\n          // a cached result) is NOT a not-found: reporting it as one told\n          // clients a URI they can list and read does not exist.\n          if (resourceContracts.some((contract) => owns(contract, uri))) {\n            throw new ProtocolError(\n              ProtocolErrorCode.InvalidParams,\n              `Resource ${uri} does not support subscriptions; only ${FILESYSTEM_FILE_URI_TEMPLATE} does. Read it again for the current contents.`,\n            );\n          }\n          throw new ResourceNotFoundError(uri, `Resource not found: ${uri}`);\n        }\n        if ((await file.subscribe(uri, notifyUpdated)) === false) {\n          // InternalError for want of anything better: ProtocolErrorCode has\n          // no resource-limit member, and the message already names the\n          // actionable cause.\n          throw new ProtocolError(\n            ProtocolErrorCode.InternalError,\n            `Subscription rejected: no watcher attached (watcher limit ${MAX_WATCHERS} reached, or fs.watch failed to start).`,\n          );\n        }\n        return {};\n      },\n    );\n\n    server.server.setRequestHandler(\n      'resources/unsubscribe',\n      (req: { params: UnsubscribeRequestParams }) => {\n        if (owns(file, req.params.uri)) file.unsubscribe(req.params.uri);\n        return {};\n      },\n    );\n  }\n\n  return {\n    dispose(): void {\n      for (const contract of resourceContracts) {\n        if (contract.destroy) {\n          contract.destroy();\n        }\n      }\n    },\n  };\n}\n"]}
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAaA,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EAChB,WAAW,GACZ,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EAAE,SAAS,EAAE,yBAAyB,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACnF,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,4BAA4B,GAC7B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAGxD,OAAO,EACL,qBAAqB,EACrB,YAAY,GAEb,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,cAAc,GACf,MAAM,mBAAmB,CAAC;AAoC3B;;;;;;GAMG;AACH,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,CACL,SAAS,CAAC,KAAK,CAAC;QAChB,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,aAAa,CAAC,CAC/E,CAAC;AACJ,CAAC;AAyCD,kEAAkE;AAClE,eAAe;AACf,kEAAkE;AAElE,SAAS,0BAA0B,CAAC,OAAoC;IACtE,MAAM,IAAI,GAAG,cAAc,CAAC,mBAAmB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IACnE,OAAO;QACL,IAAI,EAAE,6BAA6B;QACnC,KAAK,EAAE,qBAAqB;QAC5B,WAAW,EAAE,oBAAoB;QACjC,QAAQ,EAAE,eAAe;QACzB,GAAG,EAAE,gBAAgB;QACrB,WAAW,EAAE,EAAE,QAAQ,EAAE,CAAC,WAAW,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE;QACvD,SAAS,EAAE,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE;QACzE,IAAI,CAAC,GAAG;YACN,OAAO;gBACL,QAAQ,EAAE;oBACR;wBACE,GAAG,EAAE,GAAG,CAAC,IAAI;wBACb,QAAQ,EAAE,eAAe;wBACzB,IAAI;qBACL;iBACF;aACF,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAED,kEAAkE;AAClE,aAAa;AACb,kEAAkE;AAElE,SAAS,wBAAwB,CAAC,OAAoC;IACpE,MAAM,QAAQ,GAAG,OAAO,CAAC,eAAe,IAAI,qBAAqB,EAAE,CAAC;IACpE,4EAA4E;IAC5E,4EAA4E;IAC5E,oCAAoC;IACpC,MAAM,YAAY,GAAG,OAAO,CAAC,eAAe,KAAK,SAAS,CAAC;IAC3D,6EAA6E;IAC7E,kEAAkE;IAClE,0EAA0E;IAC1E,qEAAqE;IACrE,2EAA2E;IAC3E,0EAA0E;IAC1E,iEAAiE;IACjE,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IACrC,0EAA0E;IAC1E,uEAAuE;IACvE,4EAA4E;IAC5E,4EAA4E;IAC5E,2CAA2C;IAC3C,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAwC,CAAC;IAEjE,OAAO;QACL,IAAI,EAAE,qBAAqB;QAC3B,KAAK,EAAE,gBAAgB;QACvB,WAAW,EAAE,iFAAiF;QAC9F,WAAW,EAAE,4BAA4B;QACzC,WAAW,EAAE,EAAE,QAAQ,EAAE,CAAC,WAAW,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE;QACvD,mEAAmE;QACnE,0EAA0E;QAC1E,uEAAuE;QACvE,2EAA2E;QAC3E,2EAA2E;QAC3E,SAAS,EAAE,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE;QAEvE,0EAA0E;QAC1E,mEAAmE;QACnE,uEAAuE;QACvE,oCAAoC;QAEpC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,GAAkB;YAC5C,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;YACnC,0EAA0E;YAC1E,yEAAyE;YACzE,yEAAyE;YACzE,uEAAuE;YACvE,uEAAuE;YACvE,yEAAyE;YACzE,yDAAyD;YACzD,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACtC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,MAAM,IAAI,aAAa,CACrB,iBAAiB,CAAC,aAAa,EAC/B,wDAAwD,CACzD,CAAC;YACJ,CAAC;YACD,MAAM,OAAO,CAAC,SAAS,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC;YACtD,MAAM,EAAE,GAAG,IAAI,iBAAiB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YACpD,MAAM,UAAU,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;YAE5E,OAAO;gBACL,QAAQ,EAAE;oBACR;wBACE,GAAG,EAAE,GAAG,CAAC,IAAI;wBACb,QAAQ,EAAE,UAAU,CAAC,QAAQ,IAAI,0BAA0B;wBAC3D,GAAG,CAAC,UAAU,CAAC,QAAQ;4BACrB,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE;4BACjD,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;qBACpD;iBACF;aACF,CAAC;QACJ,CAAC;QAED,QAAQ,EAAE;YACR,yEAAyE;YACzE,0EAA0E;YAC1E,yEAAyE;YACzE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;gBACpB,MAAM,WAAW,GAAG,MAAM,YAAY,CACpC,OAAO,CAAC,SAAS,EACjB,iBAAiB,CAAC,KAAK,CAAC,IAAI,KAAK,CAClC,CAAC;gBACF,OAAO,WAAW,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;YAC5C,CAAC;SACF;QAED,SAAS,CAAC,GAAG,EAAE,MAAM;YACnB,0EAA0E;YAC1E,wEAAwE;YACxE,IAAI,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,OAAO,SAAS,CAAC;YAC1C,wEAAwE;YACxE,wDAAwD;YACxD,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAClC,IAAI,OAAO;gBAAE,OAAO,OAAO,CAAC;YAE5B,MAAM,OAAO,GAAG,KAAK,IAAkC,EAAE;gBACvD,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE;oBACpE,aAAa,EAAE,IAAI;iBACpB,CAAC,CAAC;gBACH,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;oBACd,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;oBACpB,OAAO,SAAS,CAAC;gBACnB,CAAC;gBAED,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;oBAChC,MAAM,IAAI,qBAAqB,CAAC,GAAG,EAAE,wCAAwC,CAAC,CAAC;gBACjF,CAAC;gBACD,IAAI,MAAM,CAAC,MAAM,KAAK,cAAc,EAAE,CAAC;oBACrC,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC;oBACzB,IAAI,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;wBACvB,MAAM,IAAI,qBAAqB,CAAC,GAAG,EAAE,uBAAuB,GAAG,KAAK,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;oBACrF,CAAC;oBACD,IAAI,SAAS,CAAC,GAAG,CAAC;wBAAE,MAAM,sBAAsB,CAAC,GAAG,CAAC,CAAC;oBACtD,MAAM,CAAC,IAAI,CACT,gDAAgD,GAAG,KAAK,yBAAyB,CAAC,GAAG,CAAC,EAAE,CACzF,CAAC;oBACF,MAAM,GAAG,CAAC;gBACZ,CAAC;gBACD,yEAAyE;gBACzE,yDAAyD;gBACzD,IAAI,MAAM,CAAC,MAAM,KAAK,OAAO;oBAAE,OAAO,SAAS,CAAC;gBAChD,qEAAqE;gBACrE,2DAA2D;gBAC3D,OAAO,KAAK,CAAC;YACf,CAAC,CAAC;YAEF,MAAM,OAAO,GAAG,OAAO,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;YAC9D,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAC3B,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,WAAW,CAAC,GAAG;YACb,sDAAsD;YACtD,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC;gBAAE,OAAO;YACpC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACxB,CAAC;QAED,OAAO;YACL,wEAAwE;YACxE,yEAAyE;YACzE,KAAK,MAAM,GAAG,IAAI,UAAU;gBAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACpD,UAAU,CAAC,KAAK,EAAE,CAAC;YACnB,IAAI,YAAY;gBAAE,QAAQ,CAAC,OAAO,EAAE,CAAC;QACvC,CAAC;KACF,CAAC;AACJ,CAAC;AAED,kEAAkE;AAClE,SAAS;AACT,kEAAkE;AAElE,SAAS,oBAAoB,CAAC,OAAoC;IAChE,OAAO;QACL,IAAI,EAAE,uBAAuB;QAC7B,KAAK,EAAE,oBAAoB;QAC3B,WAAW,EACT,8FAA8F;QAChG,QAAQ,EAAE,kBAAkB;QAC5B,WAAW,EAAE,8BAA8B;QAC3C,WAAW,EAAE,EAAE,QAAQ,EAAE,CAAC,WAAW,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE;QACvD,SAAS,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE;QACnD,IAAI;YACF,MAAM,KAAK,GAAG,OAAO,CAAC,aAAa,CAAC;YACpC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,uBAAuB;YAClD,MAAM,SAAS,GAAe,EAAE,CAAC;YACjC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;gBACvB,IAAI,CAAC;oBACH,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;oBAClC,SAAS,CAAC,IAAI,CAAC;wBACb,GAAG,EAAE,KAAK,CAAC,GAAG;wBACd,IAAI,EAAE,KAAK,CAAC,IAAI;wBAChB,WAAW,EAAE,+BAA+B,KAAK,CAAC,SAAS,EAAE;wBAC7D,QAAQ,EAAE,KAAK,CAAC,QAAQ;wBACxB,IAAI,EAAE,KAAK,CAAC,IAAI;wBAChB,WAAW,EAAE,EAAE,QAAQ,EAAE,CAAC,WAAW,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,YAAY,EAAE,KAAK,CAAC,SAAS,EAAE;qBACvF,CAAC,CAAC;gBACL,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,4DAA4D;oBAC5D,IAAI,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,SAAS;wBAAE,SAAS;oBACjE,MAAM,GAAG,CAAC;gBACZ,CAAC;YACH,CAAC;YACD,uEAAuE;YACvE,SAAS,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO,EAAE,SAAS,EAAE,CAAC;QACvB,CAAC;QACD,IAAI,CAAC,GAAG,EAAE,SAAS;YACjB,MAAM,EAAE,EAAE,EAAE,GAAG,SAAS,CAAC;YACzB,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC9C,MAAM,IAAI,aAAa,CACrB,iBAAiB,CAAC,aAAa,EAC/B,qFAAqF,CACtF,CAAC;YACJ,CAAC;YAED,IAAI,KAAK,CAAC;YACV,IAAI,CAAC;gBACH,KAAK,GAAG,OAAO,CAAC,aAAa,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;YACzD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,SAAS,EAAE,CAAC;oBACvD,MAAM,IAAI,qBAAqB,CAC7B,GAAG,CAAC,QAAQ,EAAE,EACd,oEAAoE,CACrE,CAAC;gBACJ,CAAC;gBACD,MAAM,GAAG,CAAC;YACZ,CAAC;YACD,OAAO;gBACL,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;aAC3E,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAED,kEAAkE;AAClE,mBAAmB;AACnB,kEAAkE;AAElE,MAAM,UAAU,oBAAoB,CAAC,OAAoC;IACvE,OAAO;QACL,0BAA0B,CAAC,OAAO,CAAC;QACnC,oBAAoB,CAAC,OAAO,CAAC;QAC7B,wBAAwB,CAAC,OAAO,CAAC;KAClC,CAAC;AACJ,CAAC;AAED,kEAAkE;AAClE,YAAY;AACZ,kEAAkE;AAElE;;;;;;GAMG;AACH,SAAS,sBAAsB,CAAC,KAAc;IAC5C,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC;IACjD,OAAO,IAAI,aAAa,CAAC,iBAAiB,CAAC,aAAa,EAAE,KAAK,CAAC,OAAO,EAAE;QACvE,IAAI;QACJ,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvC,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpD,CAAC,CAAC;AACL,CAAC;AAED,SAAS,QAAQ,CAAC,QAA0B;IAC1C,OAAO,KAAK,EAAE,GAAQ,EAAE,SAA4C,EAAE,GAAkB,EAAE,EAAE;QAC1F,IAAI,CAAC;YACH,OAAO,MAAM,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;QAClD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,2EAA2E;YAC3E,yDAAyD;YACzD,IAAI,KAAK,YAAY,aAAa;gBAAE,MAAM,KAAK,CAAC;YAChD,yEAAyE;YACzE,gEAAgE;YAChE,uEAAuE;YACvE,iDAAiD;YACjD,IAAI,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;gBACzB,MAAM,IAAI,qBAAqB,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;YACjE,CAAC;YACD,+DAA+D;YAC/D,uEAAuE;YACvE,gCAAgC;YAChC,IAAI,SAAS,CAAC,KAAK,CAAC;gBAAE,MAAM,sBAAsB,CAAC,KAAK,CAAC,CAAC;YAC1D,MAAM,IAAI,aAAa,CAAC,iBAAiB,CAAC,aAAa,EAAE,yBAAyB,CAAC,KAAK,CAAC,CAAC,CAAC;QAC7F,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,IAAI,CAAC,QAA0B,EAAE,GAAW;IACnD,IAAI,QAAQ,CAAC,GAAG,KAAK,SAAS;QAAE,OAAO,GAAG,KAAK,QAAQ,CAAC,GAAG,CAAC;IAC5D,OAAO,CACL,QAAQ,CAAC,WAAW,KAAK,SAAS,IAAI,IAAI,WAAW,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,IAAI,CAChG,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAA2B;IAC3D,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC3B,MAAM,OAAO,GAAG,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,KAAK,EAAE,CAAC;IAC9D,MAAM,IAAI,GAAG,wBAAwB,CAAC,OAAO,CAAC,CAAC;IAC/C,MAAM,iBAAiB,GAAG;QACxB,0BAA0B,CAAC,OAAO,CAAC;QACnC,oBAAoB,CAAC,OAAO,CAAC;QAC7B,IAAI;KACL,CAAC;IAEF,KAAK,MAAM,QAAQ,IAAI,iBAAiB,EAAE,CAAC;QACzC,MAAM,MAAM,GAAG;YACb,GAAG,CAAC,QAAQ,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAClE,GAAG,CAAC,QAAQ,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACpF,GAAG,CAAC,QAAQ,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3E,GAAG,CAAC,QAAQ,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACpF,GAAG,CAAC,QAAQ,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC/E,CAAC;QAEF,IAAI,QAAQ,CAAC,WAAW,EAAE,CAAC;YACzB,MAAM,QAAQ,GAAG,IAAI,gBAAgB,CAAC,QAAQ,CAAC,WAAW,EAAE;gBAC1D,IAAI,EAAE,QAAQ,CAAC,IAAI;gBACnB,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC9D,CAAC,CAAC;YAEH,MAAM,CAAC,gBAAgB,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC/E,CAAC;aAAM,IAAI,QAAQ,CAAC,GAAG,EAAE,CAAC;YACxB,MAAM,CAAC,gBAAgB,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,GAAQ,EAAE,GAAkB,EAAE,EAAE,CAC5F,QAAQ,CAAC,QAAQ,CAAC,CAAC,GAAG,EAAE,EAAE,EAAE,GAAG,CAAC,CACjC,CAAC;QACJ,CAAC;IACH,CAAC;IAED,wEAAwE;IACxE,0EAA0E;IAC1E,0EAA0E;IAC1E,6EAA6E;IAC7E,4EAA4E;IAC5E,wEAAwE;IACxE,uEAAuE;IACvE,qEAAqE;IACrE,4EAA4E;IAC5E,qFAAqF;IACrF,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,KAAK,QAAQ,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC;IACxE,IAAI,IAAI,CAAC,GAAG,KAAK,QAAQ,IAAI,CAAC,UAAU,EAAE,CAAC;QACzC,MAAM,CAAC,MAAM,CAAC,0BAA0B,CAAC,qBAAqB,CAAC,CAAC;QAChE,MAAM,CAAC,MAAM,CAAC,0BAA0B,CAAC,uBAAuB,CAAC,CAAC;QAElE,0EAA0E;QAC1E,0EAA0E;QAC1E,0EAA0E;QAC1E,4EAA4E;QAC5E,0EAA0E;QAC1E,gEAAgE;QAChE,MAAM,aAAa,GAAG,CAAC,UAAkB,EAAQ,EAAE;YACjD,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;gBAClB,IAAI,CAAC,QAAQ,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC;gBAC1C,OAAO;YACT,CAAC;YACD,MAAM,aAAa,GAAsC,EAAE,GAAG,EAAE,UAAU,EAAE,CAAC;YAC7E,sEAAsE;YACtE,KAAK,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,aAAa,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;gBAC3E,MAAM,CAAC,KAAK,CAAC,+BAA+B,EAAE;oBAC5C,GAAG,EAAE,UAAU;oBACf,KAAK,EAAE,yBAAyB,CAAC,GAAG,CAAC;iBACtC,CAAC,CAAC;YACL,CAAC,CAAC,CAAC;QACL,CAAC,CAAC;QAEF,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAC7B,qBAAqB,EACrB,KAAK,EAAE,GAAuC,EAAE,EAAE;YAChD,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC;YAC3B,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;gBACrB,oEAAoE;gBACpE,gEAAgE;gBAChE,uDAAuD;gBACvD,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC;oBAC9D,MAAM,IAAI,aAAa,CACrB,iBAAiB,CAAC,aAAa,EAC/B,YAAY,GAAG,yCAAyC,4BAA4B,gDAAgD,CACrI,CAAC;gBACJ,CAAC;gBACD,MAAM,IAAI,qBAAqB,CAAC,GAAG,EAAE,uBAAuB,GAAG,EAAE,CAAC,CAAC;YACrE,CAAC;YACD,IAAI,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC;gBACzD,mEAAmE;gBACnE,8DAA8D;gBAC9D,oBAAoB;gBACpB,MAAM,IAAI,aAAa,CACrB,iBAAiB,CAAC,aAAa,EAC/B,6DAA6D,YAAY,yCAAyC,CACnH,CAAC;YACJ,CAAC;YACD,OAAO,EAAE,CAAC;QACZ,CAAC,CACF,CAAC;QAEF,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAC7B,uBAAuB,EACvB,CAAC,GAAyC,EAAE,EAAE;YAC5C,IAAI,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC;gBAAE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,OAAO,EAAE,CAAC;QACZ,CAAC,CACF,CAAC;IACJ,CAAC;IAED,OAAO;QACL,OAAO;YACL,KAAK,MAAM,QAAQ,IAAI,iBAAiB,EAAE,CAAC;gBACzC,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;oBACrB,QAAQ,CAAC,OAAO,EAAE,CAAC;gBACrB,CAAC;YACH,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["import type {\n  CacheHint,\n  CompleteResourceTemplateCallback,\n  McpServer,\n  ReadResourceResult,\n  Resource,\n  ResourceUpdatedNotificationParams,\n  Role,\n  ServerContext,\n  ServerNotifier,\n  SubscribeRequestParams,\n  UnsubscribeRequestParams,\n} from '@modelcontextprotocol/server';\nimport {\n  ProtocolError,\n  ProtocolErrorCode,\n  ResourceNotFoundError,\n  ResourceTemplate,\n  UriTemplate,\n} from '@modelcontextprotocol/server';\n\nimport type { FsError } from './core/errors.ts';\nimport { ErrorCode, formatUnknownErrorMessage, isFsError } from './core/errors.ts';\nimport {\n  decodeFileUriPath,\n  encodeFileUriPath,\n  extractPath,\n  FILESYSTEM_FILE_URI_TEMPLATE,\n} from './core/file-uri.ts';\nimport { GuardedFileSystem } from './core/fs.ts';\nimport { Logger } from './core/observability.ts';\nimport { suggestPaths } from './core/path-completer.ts';\nimport type { PathGuard } from './core/path.ts';\nimport type { ResourceStore } from './core/store.ts';\nimport {\n  createWatcherRegistry,\n  MAX_WATCHERS,\n  type WatcherRegistry,\n} from './core/watcher-registry.ts';\nimport {\n  buildSectionsRecord,\n  INSTRUCTIONS_SUMMARY,\n  INSTRUCTIONS_URI,\n  renderSections,\n} from './instructions.ts';\n\n// ═══════════════════════════════════════════════════════════════\n// shared\n// ═══════════════════════════════════════════════════════════════\n\nexport interface ResourceRegistrationOptions {\n  resourceStore: ResourceStore;\n  pathGuard: PathGuard;\n  /** Mirrors the `--read-only` gate so the instructions match the tools actually registered. */\n  readOnly: boolean;\n  /**\n   * Shared file-watcher registry for the modern (per-request) HTTP leg. When set,\n   * the resource uses this handler-scoped registry instead of creating its own\n   * per-server one, so file-change watchers persist across requests and publish\n   * to the shared ServerEventBus. Omitted (per-server registry) on legacy/stdio.\n   */\n  watcherRegistry?: WatcherRegistry;\n  /** Modern-leg typed notification publisher. */\n  notifier?: ServerNotifier;\n  /** The protocol era this instance serves; omitted where the caller does not know. */\n  era?: 'legacy' | 'modern';\n  /**\n   * Scope for shared-content cache hints. 'private' when the endpoint is\n   * API-key gated, mirroring the list hints in server.ts — a shared cache must\n   * not store an authenticated response body. Defaults to 'public'.\n   */\n  cacheScope?: 'public' | 'private';\n}\n\ntype ResourceRegistrarDeps = Omit<ResourceRegistrationOptions, 'pathGuard' | 'readOnly'> & {\n  readonly server: McpServer;\n  readonly pathGuard: PathGuard;\n  readonly readOnly?: boolean;\n};\n\n/**\n * A filesystem failure that reads as not-found on the resource wire, for both\n * `resources/read` and `resources/subscribe`. ACCESS_DENIED folds in\n * deliberately: masking whether an out-of-root or denylisted path exists is the\n * security-correct answer, and the `FsError` message still carries the real\n * cause to the client.\n */\nfunction isNotFoundish(error: unknown): error is FsError {\n  return (\n    isFsError(error) &&\n    (error.code === ErrorCode.NOT_FOUND || error.code === ErrorCode.ACCESS_DENIED)\n  );\n}\n\n// ═══════════════════════════════════════════════════════════════\n// contract\n// ═══════════════════════════════════════════════════════════════\n\ninterface ResourceContract {\n  name: string;\n  title?: string;\n  description?: string;\n  mimeType?: string;\n  cacheHint?: CacheHint;\n  annotations?: {\n    audience?: Role[];\n    priority?: number;\n  };\n  /** A fixed, enumerable URI (e.g. internal://instructions)... */\n  uri?: string;\n  /** ...or a URI template, optionally with a completer for its variable. */\n  uriTemplate?: string;\n  complete?: { path: CompleteResourceTemplateCallback };\n  readonly read: (\n    uri: URL,\n    variables: Record<string, string | string[]>,\n    ctx: ServerContext,\n  ) => Promise<ReadResourceResult> | ReadResourceResult;\n  readonly subscribe?: (\n    uri: string,\n    notify: (uri: string) => void,\n  ) => Promise<boolean | undefined> | boolean | undefined;\n  readonly unsubscribe?: (uri: string) => void;\n  readonly destroy?: () => void;\n  readonly list?: (\n    ctx: ServerContext,\n  ) => Promise<{ resources: Resource[] }> | { resources: Resource[] };\n}\n\n/** The one contract with a live watcher behind it. */\ntype SubscribableContract = ResourceContract &\n  Required<Pick<ResourceContract, 'subscribe' | 'unsubscribe'>>;\n\n// ═══════════════════════════════════════════════════════════════\n// instructions\n// ═══════════════════════════════════════════════════════════════\n\nfunction createInstructionsResource(options: ResourceRegistrationOptions): ResourceContract {\n  const text = renderSections(buildSectionsRecord(options.readOnly));\n  return {\n    name: 'filesystem-mcp-instructions',\n    title: 'Server Instructions',\n    description: INSTRUCTIONS_SUMMARY,\n    mimeType: 'text/markdown',\n    uri: INSTRUCTIONS_URI,\n    annotations: { audience: ['assistant'], priority: 0.8 },\n    cacheHint: { cacheScope: options.cacheScope ?? 'public', ttlMs: 300_000 },\n    read(uri) {\n      return {\n        contents: [\n          {\n            uri: uri.href,\n            mimeType: 'text/markdown',\n            text,\n          },\n        ],\n      };\n    },\n  };\n}\n\n// ═══════════════════════════════════════════════════════════════\n// filesystem\n// ═══════════════════════════════════════════════════════════════\n\nfunction createFilesystemResource(options: ResourceRegistrationOptions): SubscribableContract {\n  const registry = options.watcherRegistry ?? createWatcherRegistry();\n  // Only the per-server (legacy/stdio) registry is owned by this resource and\n  // destroyed on dispose; the shared modern-leg registry is owned by the host\n  // and torn down at server shutdown.\n  const ownsRegistry = options.watcherRegistry === undefined;\n  // The URIs this connection holds a `resources/subscribe` lease for. The wire\n  // verb is per-URI and idempotent — a second subscribe is the same\n  // subscription, and one unsubscribe ends it — but the registry ref-counts\n  // leases (the HTTP listen leg needs that). Without this set a double\n  // subscribe took two leases that one unsubscribe could not release, and an\n  // unsubscribe for a URI never subscribed released a lease this connection\n  // never took, dropping a watcher some other holder still wanted.\n  const leasedUris = new Set<string>();\n  // Subscribes mid-acquire, keyed by URI. Two concurrent subscribes for the\n  // same URI must share one acquire: both passing the `leasedUris` check\n  // before either finished took two registry leases that the single set entry\n  // could release only once — on the shared modern registry that orphan lease\n  // pinned a watcher until process shutdown.\n  const inflight = new Map<string, Promise<boolean | undefined>>();\n\n  return {\n    name: 'filesystem-mcp-file',\n    title: 'Workspace File',\n    description: 'Read a file from the workspace. Subscribe to get updates when the file changes.',\n    uriTemplate: FILESYSTEM_FILE_URI_TEMPLATE,\n    annotations: { audience: ['assistant'], priority: 0.8 },\n    // Without this the SDK falls back to its conservative `{ ttlMs: 0,\n    // cacheScope: 'private' }`, making every file read uncacheable — and this\n    // is the one resource with a live invalidation channel, so TTL and the\n    // watcher compose exactly as the spec's caching section describes. The TTL\n    // stays short because a non-subscriber gets no invalidation signal at all.\n    cacheHint: { cacheScope: options.cacheScope ?? 'public', ttlMs: 5_000 },\n\n    // No `list`: the template registers with `list: undefined` — readable but\n    // not enumerable. Listing each allowed root as a concrete resource\n    // duplicated the template and grew resources/list linearly with roots;\n    // `list_roots` owns root discovery.\n\n    async read(uri, _variables, ctx: ServerContext) {\n      ctx.mcpReq.signal.throwIfAborted();\n      // Decode via extractPath — the same decoder resources/subscribe uses — so\n      // both consumers are symmetric with buildFileResourceUri's encoding. The\n      // {+path} template variable arrives still percent-encoded, so validating\n      // it directly would treat \"c%3A/proj/a.ts\" as a literal relative path;\n      // no fallback to it here, or the two branches would validate different\n      // strings. extractPath only fails past the template match on undecodable\n      // percent-encoding, which is the caller's malformed URI.\n      const rawPath = extractPath(uri.href);\n      if (rawPath === undefined) {\n        throw new ProtocolError(\n          ProtocolErrorCode.InvalidParams,\n          'Malformed file URI: path is not valid percent-encoding',\n        );\n      }\n      await options.pathGuard.validateExistingPath(rawPath);\n      const fs = new GuardedFileSystem(options.pathGuard);\n      const readResult = await fs.readRaw(rawPath, { signal: ctx.mcpReq.signal });\n\n      return {\n        contents: [\n          {\n            uri: uri.href,\n            mimeType: readResult.mimeType || 'application/octet-stream',\n            ...(readResult.isBinary\n              ? { blob: readResult.content.toString('base64') }\n              : { text: readResult.content.toString('utf-8') }),\n          },\n        ],\n      };\n    },\n\n    complete: {\n      // Both ends speak the `{+path}` form (see encodeFileUriPath), not raw OS\n      // paths: the partial arriving here is whatever this returned last, so the\n      // decode mirrors the encode. An undecodable partial is matched as typed.\n      path: async (value) => {\n        const suggestions = await suggestPaths(\n          options.pathGuard,\n          decodeFileUriPath(value) ?? value,\n        );\n        return suggestions.map(encodeFileUriPath);\n      },\n    },\n\n    subscribe(uri, notify) {\n      // Already subscribed on this connection: the watcher is live and the sink\n      // is registered, so this is a no-op success rather than a second lease.\n      if (leasedUris.has(uri)) return undefined;\n      // A subscribe for this URI is mid-acquire: share its outcome instead of\n      // taking a second lease the lease set cannot represent.\n      const pending = inflight.get(uri);\n      if (pending) return pending;\n\n      const acquire = async (): Promise<boolean | undefined> => {\n        const result = await registry.acquire(options.pathGuard, uri, notify, {\n          markSubscribe: true,\n        });\n        if (result.ok) {\n          leasedUris.add(uri);\n          return undefined;\n        }\n\n        if (result.reason === 'bad-uri') {\n          throw new ResourceNotFoundError(uri, `Cannot subscribe: not a filesystem URI`);\n        }\n        if (result.reason === 'invalid-path') {\n          const err = result.error;\n          if (isNotFoundish(err)) {\n            throw new ResourceNotFoundError(uri, `Cannot subscribe to ${uri}: ${err.message}`);\n          }\n          if (isFsError(err)) throw fsErrorToProtocolError(err);\n          Logger.warn(\n            `Unexpected error validating path for watcher ${uri}: ${formatUnknownErrorMessage(err)}`,\n          );\n          throw err;\n        }\n        // Unsubscribed (or the registry destroyed) mid-await: the caller already\n        // asked for this to stop, so there is nothing to reject.\n        if (result.reason === 'stale') return undefined;\n        // capped / attach-failed: `false` tells the handler to reject, since\n        // undefined would report success with no watcher attached.\n        return false;\n      };\n\n      const promise = acquire().finally(() => inflight.delete(uri));\n      inflight.set(uri, promise);\n      return promise;\n    },\n\n    unsubscribe(uri) {\n      // Only release a lease this connection actually took.\n      if (!leasedUris.delete(uri)) return;\n      registry.release(uri);\n    },\n\n    destroy() {\n      // Release what this connection still holds before the registry goes: on\n      // the shared (modern) registry nothing else would ever end these leases.\n      for (const uri of leasedUris) registry.release(uri);\n      leasedUris.clear();\n      if (ownsRegistry) registry.destroy();\n    },\n  };\n}\n\n// ═══════════════════════════════════════════════════════════════\n// result\n// ═══════════════════════════════════════════════════════════════\n\nfunction createResultResource(options: ResourceRegistrationOptions): ResourceContract {\n  return {\n    name: 'filesystem-mcp-result',\n    title: 'Cached Tool Result',\n    description:\n      'Ephemeral cached tool output. Listed via resources/list; entries expire after the cache TTL.',\n    mimeType: 'application/json',\n    uriTemplate: 'filesystem-mcp://result/{id}',\n    annotations: { audience: ['assistant'], priority: 0.3 },\n    cacheHint: { cacheScope: 'private', ttlMs: 60_000 },\n    list() {\n      const store = options.resourceStore;\n      const uris = store.keys(); // prunes expired first\n      const resources: Resource[] = [];\n      for (const uri of uris) {\n        try {\n          const entry = store.getEntry(uri);\n          resources.push({\n            uri: entry.uri,\n            name: entry.name,\n            description: `Cached tool result; expires ${entry.expiresAt}`,\n            mimeType: entry.mimeType,\n            size: entry.size,\n            annotations: { audience: ['assistant'], priority: 0.3, lastModified: entry.createdAt },\n          });\n        } catch (err) {\n          // An entry may expire between keys() and getEntry; skip it.\n          if (isFsError(err) && err.code === ErrorCode.NOT_FOUND) continue;\n          throw err;\n        }\n      }\n      // Recent-first: keys() returns insertion order, so the newest is last.\n      resources.reverse();\n      return { resources };\n    },\n    read(uri, variables) {\n      const { id } = variables;\n      if (typeof id !== 'string' || id.length === 0) {\n        throw new ProtocolError(\n          ProtocolErrorCode.InvalidParams,\n          'Malformed result URI: missing {id}. Use the exact resourceUri returned by the tool.',\n        );\n      }\n\n      let entry;\n      try {\n        entry = options.resourceStore.getEntry(uri.toString());\n      } catch (err) {\n        if (isFsError(err) && err.code === ErrorCode.NOT_FOUND) {\n          throw new ResourceNotFoundError(\n            uri.toString(),\n            'Cached result not found or expired. Re-run the tool to regenerate.',\n          );\n        }\n        throw err;\n      }\n      return {\n        contents: [{ uri: entry.uri, mimeType: entry.mimeType, text: entry.text }],\n      };\n    },\n  };\n}\n\n// ═══════════════════════════════════════════════════════════════\n// export contracts\n// ═══════════════════════════════════════════════════════════════\n\nexport function getResourceContracts(options: ResourceRegistrationOptions): ResourceContract[] {\n  return [\n    createInstructionsResource(options),\n    createResultResource(options),\n    createFilesystemResource(options),\n  ];\n}\n\n// ═══════════════════════════════════════════════════════════════\n// registrar\n// ═══════════════════════════════════════════════════════════════\n\n/**\n * A caller-traceable FsError as the SDK's InvalidParams error. The Problem's\n * identity fields ride the SDK's error.data channel: `message` stays the\n * wire message, and code/path/suggestion give clients a machine-readable\n * view. Keyed by `code`, so it cannot collide with the\n * ResourceNotFoundError convention (data: { uri } and nothing else).\n */\nfunction fsErrorToProtocolError(error: FsError): ProtocolError {\n  const { code, path, suggestion } = error.problem;\n  return new ProtocolError(ProtocolErrorCode.InvalidParams, error.message, {\n    code,\n    ...(path !== undefined ? { path } : {}),\n    ...(suggestion !== undefined ? { suggestion } : {}),\n  });\n}\n\nfunction wrapRead(contract: ResourceContract) {\n  return async (uri: URL, variables: Record<string, string | string[]>, ctx: ServerContext) => {\n    try {\n      return await contract.read(uri, variables, ctx);\n    } catch (error) {\n      // The SDK brands ProtocolError with `static [Symbol.hasInstance]`, so this\n      // holds across separately bundled SDK copies and realms.\n      if (error instanceof ProtocolError) throw error;\n      // A missing or out-of-root path is a not-found, not a malformed request.\n      // The SDK puts ResourceNotFoundError on the wire as -32602 with\n      // `data.uri`, which is what clients match on; -32002 is the older code\n      // they also accept, and this SDK never emits it.\n      if (isNotFoundish(error)) {\n        throw new ResourceNotFoundError(uri.toString(), error.message);\n      }\n      // A remaining FsError (NOT_FILE, TOO_LARGE, ...) traces to the\n      // caller-supplied URI; anything else is a server-side failure and must\n      // not be blamed on the request.\n      if (isFsError(error)) throw fsErrorToProtocolError(error);\n      throw new ProtocolError(ProtocolErrorCode.InternalError, formatUnknownErrorMessage(error));\n    }\n  };\n}\n\n/**\n * Whether `contract` answers for `uri`, decided by the template matcher the SDK\n * dispatches `resources/read` with, so `resources/subscribe` and\n * `resources/read` agree on which resource owns a URI. Not\n * `checkResourceAllowed`: that is an RFC 8707 audience check comparing\n * `URL.origin`, which is the opaque `\"null\"` for every custom scheme, so it\n * matched `filesystem-mcp://result/…` — and any other scheme — to the file\n * template.\n */\nfunction owns(contract: ResourceContract, uri: string): boolean {\n  if (contract.uri !== undefined) return uri === contract.uri;\n  return (\n    contract.uriTemplate !== undefined && new UriTemplate(contract.uriTemplate).match(uri) !== null\n  );\n}\n\nexport function registerResources(deps: ResourceRegistrarDeps): { dispose(): void } {\n  const server = deps.server;\n  const options = { ...deps, readOnly: deps.readOnly ?? false };\n  const file = createFilesystemResource(options);\n  const resourceContracts = [\n    createInstructionsResource(options),\n    createResultResource(options),\n    file,\n  ];\n\n  for (const contract of resourceContracts) {\n    const config = {\n      ...(contract.title !== undefined ? { title: contract.title } : {}),\n      ...(contract.description !== undefined ? { description: contract.description } : {}),\n      ...(contract.mimeType !== undefined ? { mimeType: contract.mimeType } : {}),\n      ...(contract.annotations !== undefined ? { annotations: contract.annotations } : {}),\n      ...(contract.cacheHint !== undefined ? { cacheHint: contract.cacheHint } : {}),\n    };\n\n    if (contract.uriTemplate) {\n      const template = new ResourceTemplate(contract.uriTemplate, {\n        list: contract.list,\n        ...(contract.complete ? { complete: contract.complete } : {}),\n      });\n\n      server.registerResource(contract.name, template, config, wrapRead(contract));\n    } else if (contract.uri) {\n      server.registerResource(contract.name, contract.uri, config, (uri: URL, ctx: ServerContext) =>\n        wrapRead(contract)(uri, {}, ctx),\n      );\n    }\n  }\n\n  // `resources/subscribe`/`unsubscribe` are 2025-era-only verbs; a modern\n  // server answers `-32601 Method not found` for them, so registering these\n  // handlers on a modern-era instance would dispatch to code no request can\n  // reach. A legacy instance on the HTTP leg (the one built with a `notifier`)\n  // lives for one request: a subscription accepted there would take a watcher\n  // lease for an instance that is gone before the file changes. Leave the\n  // handlers off so the SDK refuses the verb, and no lease is taken. The\n  // predicate mirrors the capability gate in server.ts exactly, so the\n  // handler is registered if and only if `resources.subscribe` is advertised.\n  // sunset(SEP-2577): removal trigger in docs/adr/002-legacy-protocol-paths-sunset.md.\n  const legacyHttp = deps.era === 'legacy' && deps.notifier !== undefined;\n  if (deps.era !== 'modern' && !legacyHttp) {\n    server.server.assertCanSetRequestHandler('resources/subscribe');\n    server.server.assertCanSetRequestHandler('resources/unsubscribe');\n\n    // One stable callback for the whole registrar, NOT one per subscribe. The\n    // registry holds these in a Set keyed by identity, so a fresh closure per\n    // request made a second `resources/subscribe` for the same URI register a\n    // second sink: one file change then sent N notifications, and `unsubscribe`\n    // (which only ends a lease) removed none of them. Subscribe is per-URI on\n    // the wire, so the sink must be too — this makes it idempotent.\n    const notifyUpdated = (updatedUri: string): void => {\n      if (deps.notifier) {\n        deps.notifier.resourceUpdated(updatedUri);\n        return;\n      }\n      const updatePayload: ResourceUpdatedNotificationParams = { uri: updatedUri };\n      // A failed notify means the connection went away; nothing to recover.\n      void server.server.sendResourceUpdated(updatePayload).catch((err: unknown) => {\n        Logger.debug('resource update not delivered', {\n          uri: updatedUri,\n          error: formatUnknownErrorMessage(err),\n        });\n      });\n    };\n\n    server.server.setRequestHandler(\n      'resources/subscribe',\n      async (req: { params: SubscribeRequestParams }) => {\n        const { uri } = req.params;\n        if (!owns(file, uri)) {\n          // A resource that exists but has no watcher (the instructions text,\n          // a cached result) is NOT a not-found: reporting it as one told\n          // clients a URI they can list and read does not exist.\n          if (resourceContracts.some((contract) => owns(contract, uri))) {\n            throw new ProtocolError(\n              ProtocolErrorCode.InvalidParams,\n              `Resource ${uri} does not support subscriptions; only ${FILESYSTEM_FILE_URI_TEMPLATE} does. Read it again for the current contents.`,\n            );\n          }\n          throw new ResourceNotFoundError(uri, `Resource not found: ${uri}`);\n        }\n        if ((await file.subscribe(uri, notifyUpdated)) === false) {\n          // InternalError for want of anything better: ProtocolErrorCode has\n          // no resource-limit member, and the message already names the\n          // actionable cause.\n          throw new ProtocolError(\n            ProtocolErrorCode.InternalError,\n            `Subscription rejected: no watcher attached (watcher limit ${MAX_WATCHERS} reached, or fs.watch failed to start).`,\n          );\n        }\n        return {};\n      },\n    );\n\n    server.server.setRequestHandler(\n      'resources/unsubscribe',\n      (req: { params: UnsubscribeRequestParams }) => {\n        if (owns(file, req.params.uri)) file.unsubscribe(req.params.uri);\n        return {};\n      },\n    );\n  }\n\n  return {\n    dispose(): void {\n      for (const contract of resourceContracts) {\n        if (contract.destroy) {\n          contract.destroy();\n        }\n      }\n    },\n  };\n}\n"]}

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,cAAc,EACf,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAKzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAgBlE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,mBAAmB,IAAI,IAAI,CAAC;CAC7B;AAED,wBAAsB,YAAY,CAChC,OAAO,GAAE,aAAkB,EAC3B,SAAS,CAAC,EAAE;IACV,0EAA0E;IAC1E,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;OAGG;IACH,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B,qFAAqF;IACrF,GAAG,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GACA,OAAO,CAAC,uBAAuB,CAAC,CAgIlC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,cAAc,EACf,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAKzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAgBlE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,mBAAmB,IAAI,IAAI,CAAC;CAC7B;AAED,wBAAsB,YAAY,CAChC,OAAO,GAAE,aAAkB,EAC3B,SAAS,CAAC,EAAE;IACV,0EAA0E;IAC1E,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;OAGG;IACH,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B,qFAAqF;IACrF,GAAG,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GACA,OAAO,CAAC,uBAAuB,CAAC,CAiIlC"}

package/dist/server.js

@@ -27,6 +27,7 @@ export async function createServer(options = {}, extraDeps) {
     // one request, registers no subscribe handler (resources.ts, same
     // predicate) and sends no notification of any kind — there is no stream to
     // send it on — so neither `subscribe` nor `listChanged` is advertised.
+    // sunset(SEP-2577): removal trigger in docs/adr/002-legacy-protocol-paths-sunset.md.
     const legacyHttp = extraDeps?.era === 'legacy' && extraDeps.notifier !== undefined;
     const capabilities = {
         resources: { subscribe: !legacyHttp, listChanged: !legacyHttp },

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  Implementation,\n  ServerCapabilities,\n  ServerNotifier,\n} from '@modelcontextprotocol/server';\nimport { McpServer } from '@modelcontextprotocol/server';\n\nimport packageJson from '../package.json' with { type: 'json' };\nimport { requestStateCodec } from './core/input-required.ts';\nimport { Logger } from './core/observability.ts';\nimport type { ServerOptions } from './core/path.ts';\nimport { PathGuard } from './core/path.ts';\nimport { PageSnapshotStore, ResourceStore } from './core/store.ts';\nimport type { WatcherRegistry } from './core/watcher-registry.ts';\nimport { INSTRUCTIONS_SUMMARY, INSTRUCTIONS_URI } from './instructions.ts';\nimport { registerPrompts } from './prompts.ts';\nimport { registerResources } from './resources.ts';\nimport { registerTools } from './tools/index.ts';\n\n// ═══════════════════════════════════════════════════════════════\n// bootstrap\n// ═══════════════════════════════════════════════════════════════\n\nconst {\n  version: SERVER_VERSION,\n  description: SERVER_DESCRIPTION,\n  homepage: SERVER_HOMEPAGE,\n} = packageJson;\n\nexport interface FilesystemServerContext {\n  readonly mcp: McpServer;\n  readonly pathGuard: PathGuard;\n  disposeRuntimeState(): void;\n}\n\nexport async function createServer(\n  options: ServerOptions = {},\n  extraDeps?: {\n    /** Shared file-watcher registry for the modern (per-request) HTTP leg. */\n    watcherRegistry?: WatcherRegistry;\n    /** Modern-leg typed notification publisher. */\n    notifier?: ServerNotifier;\n    /**\n     * Guard to use instead of constructing one. The HTTP leg builds a single\n     * guard for the whole endpoint and passes it to every per-request instance,\n     * so an accepted access grant survives the request that accepted it (R8) and\n     * the listen-watcher path validates against the same allowed set. Omitted on\n     * stdio, where the instance is pinned for the connection and owns its guard.\n     */\n    pathGuard?: PathGuard;\n    /**\n     * Store to use instead of constructing one. The HTTP modern leg shares one\n     * store across every per-request instance, so a result a tool externalized\n     * in one POST survives to the follow-up resources/read. Omitted on stdio,\n     * where the pinned instance owns its store for the connection.\n     */\n    resourceStore?: ResourceStore;\n    /**\n     * Pagination snapshots shared by every modern HTTP request. Omitted on\n     * stdio, where the connection-owned context clears its store on close.\n     */\n    pageStore?: PageSnapshotStore;\n    /** The protocol era this instance serves; omitted where the caller does not know. */\n    era?: 'legacy' | 'modern';\n    /**\n     * The resolved HTTP credential, from `--api-key` or `FS_API_KEY`. Lives here\n     * rather than on `ServerOptions` because that object is `PathGuard`'s\n     * constructor argument and is exposed on its public `options` field — a\n     * bearer secret has no business being reachable from a tool handler.\n     */\n    apiKey?: string;\n  },\n): Promise<FilesystemServerContext> {\n  // Only `resources` is declared: `McpServer` advertises `tools` and `prompts`\n  // (with `listChanged: true`) and `completions` from the registrations below,\n  // but never infers `subscribe`.\n  //\n  // `resources.subscribe` stays advertised on both eras: the verb itself is\n  // 2025-only, but the SDK's listen router honors a `subscriptions/listen`\n  // resource filter only while this bit is advertised (dist: `allow(\n  // capabilities?.resources?.subscribe)` on `resourceSubscriptions`). The\n  // strict-capability gate on outbound `notifications/resources/updated`\n  // checks only that `resources` exists. The one exception is a\n  // legacy instance on the HTTP leg (era 'legacy' with a notifier): it serves\n  // one request, registers no subscribe handler (resources.ts, same\n  // predicate) and sends no notification of any kind — there is no stream to\n  // send it on — so neither `subscribe` nor `listChanged` is advertised.\n  const legacyHttp = extraDeps?.era === 'legacy' && extraDeps.notifier !== undefined;\n  const capabilities = {\n    resources: { subscribe: !legacyHttp, listChanged: !legacyHttp },\n  } satisfies ServerCapabilities;\n\n  const cacheScope: 'private' | 'public' = extraDeps?.apiKey ? 'private' : 'public';\n  const serverConfig: NonNullable<ConstructorParameters<typeof McpServer>[1]> = {\n    capabilities,\n    enforceStrictCapabilities: true,\n    cacheHints: {\n      'tools/list': { ttlMs: 3_600_000, cacheScope },\n      'prompts/list': { ttlMs: 3_600_000, cacheScope },\n      // Always private, never `cacheScope`: this list enumerates the\n      // ResourceStore, so its entries are one caller's externalized tool output\n      // — the same entries whose own read hint is `private` (resources.ts). The\n      // other four lists are the same for every caller and follow the key, and\n      // they are built from frozen module-level arrays that cannot change at\n      // runtime, so an hour is honest: a shorter hint only buys the client a\n      // re-fetch of bytes that cannot have differed, at the cost of the prompt\n      // cache stability the spec asks deterministic ordering to preserve.\n      'resources/list': { ttlMs: 30_000, cacheScope: 'private' },\n      'resources/templates/list': { ttlMs: 3_600_000, cacheScope },\n      'server/discover': { ttlMs: 3_600_000, cacheScope },\n    },\n    // Multi-round-trip `requestState` integrity (protocol revision 2026-07-28):\n    // the codec verifies the HMAC on every retried round before the handler\n    // runs, so a tampered or expired state is rejected as `-32602` rather than\n    // trusted. The decoded `PendingState` reaches handlers via\n    // `ctx.mcpReq.requestState<T>()`.\n    // eslint-disable-next-line @typescript-eslint/unbound-method\n    requestState: { verify: requestStateCodec.verify },\n    // The ResourceStore fires list-changed on every externalization and on\n    // every expiry prune (store.ts), so parallel tools/call on one\n    // connection can send the same notification several times in one tick;\n    // each copy makes the client refetch an unchanged list. The SDK\n    // coalesces same-tick duplicates for methods listed here.\n    // ponytail: same-tick coalescing only — cross-tick bursts (batch\n    // externalizations separated by fs awaits) still fan out; a store-level\n    // debounce is the fix if clients ever report that. The modern HTTP leg\n    // publishes through the ServerEventBus, which this option does not\n    // touch, so it protects the stdio/in-memory leg.\n    debouncedNotificationMethods: ['notifications/resources/list_changed'],\n  };\n\n  serverConfig.instructions =\n    `${INSTRUCTIONS_SUMMARY} ` +\n    `For full guidance, read ${INSTRUCTIONS_URI} or run the get-help prompt.`;\n\n  const implementation: Implementation = {\n    name: 'filesystem-mcp',\n    title: 'Filesystem MCP',\n    version: SERVER_VERSION,\n    ...(SERVER_DESCRIPTION ? { description: SERVER_DESCRIPTION } : {}),\n    ...(SERVER_HOMEPAGE ? { websiteUrl: SERVER_HOMEPAGE } : {}),\n  };\n  const server = new McpServer(implementation, serverConfig);\n  server.server.fallbackNotificationHandler = (notification) => {\n    Logger.debug('Unhandled client notification', { method: notification.method });\n    return Promise.resolve();\n  };\n\n  // A failed send means the connection went away; nothing to recover.\n  const resourceStore =\n    extraDeps?.resourceStore ??\n    new ResourceStore(() => {\n      if (extraDeps?.notifier) {\n        extraDeps.notifier.resourcesChanged();\n        return;\n      }\n      void server.server.sendResourceListChanged().catch((error: unknown) => {\n        Logger.debug('resource list_changed not delivered', { error: String(error) });\n      });\n    });\n  const pageStore = extraDeps?.pageStore ?? new PageSnapshotStore();\n\n  const pathGuard = extraDeps?.pathGuard ?? new PathGuard(options);\n  // Recompute once per guard, keyed on the guard's own state rather than on\n  // whether it was injected — an injected-but-uninitialized guard would\n  // otherwise deny every path. Not unconditional: the HTTP leg shares one guard\n  // across a fresh instance per request, and a repeat recompute would both redo\n  // the root resolution per request and race a concurrent `applyGrant`, which\n  // commits under a mutation lock this call does not take.\n  if (!pathGuard.isInitialized()) await pathGuard.recomputeAllowedDirectories();\n\n  const deps = {\n    server,\n    pathGuard,\n    pageStore,\n    resourceStore,\n    cacheScope,\n    ...(options.readOnly ? { readOnly: true } : {}),\n    ...(extraDeps?.watcherRegistry ? { watcherRegistry: extraDeps.watcherRegistry } : {}),\n    ...(extraDeps?.notifier ? { notifier: extraDeps.notifier } : {}),\n    ...(extraDeps?.era ? { era: extraDeps.era } : {}),\n  };\n\n  const resourceDisposable = registerResources(deps);\n  registerPrompts(deps);\n  registerTools(deps);\n\n  // False when the store is shared across instances and outlives this one.\n  const ownsPages = extraDeps?.pageStore === undefined;\n  let cleanedUp = false;\n  return {\n    mcp: server,\n    pathGuard,\n    disposeRuntimeState() {\n      if (cleanedUp) return;\n      cleanedUp = true;\n      if (ownsPages) pageStore.clear();\n      resourceDisposable.dispose();\n    },\n  };\n}\n"]}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  Implementation,\n  ServerCapabilities,\n  ServerNotifier,\n} from '@modelcontextprotocol/server';\nimport { McpServer } from '@modelcontextprotocol/server';\n\nimport packageJson from '../package.json' with { type: 'json' };\nimport { requestStateCodec } from './core/input-required.ts';\nimport { Logger } from './core/observability.ts';\nimport type { ServerOptions } from './core/path.ts';\nimport { PathGuard } from './core/path.ts';\nimport { PageSnapshotStore, ResourceStore } from './core/store.ts';\nimport type { WatcherRegistry } from './core/watcher-registry.ts';\nimport { INSTRUCTIONS_SUMMARY, INSTRUCTIONS_URI } from './instructions.ts';\nimport { registerPrompts } from './prompts.ts';\nimport { registerResources } from './resources.ts';\nimport { registerTools } from './tools/index.ts';\n\n// ═══════════════════════════════════════════════════════════════\n// bootstrap\n// ═══════════════════════════════════════════════════════════════\n\nconst {\n  version: SERVER_VERSION,\n  description: SERVER_DESCRIPTION,\n  homepage: SERVER_HOMEPAGE,\n} = packageJson;\n\nexport interface FilesystemServerContext {\n  readonly mcp: McpServer;\n  readonly pathGuard: PathGuard;\n  disposeRuntimeState(): void;\n}\n\nexport async function createServer(\n  options: ServerOptions = {},\n  extraDeps?: {\n    /** Shared file-watcher registry for the modern (per-request) HTTP leg. */\n    watcherRegistry?: WatcherRegistry;\n    /** Modern-leg typed notification publisher. */\n    notifier?: ServerNotifier;\n    /**\n     * Guard to use instead of constructing one. The HTTP leg builds a single\n     * guard for the whole endpoint and passes it to every per-request instance,\n     * so an accepted access grant survives the request that accepted it (R8) and\n     * the listen-watcher path validates against the same allowed set. Omitted on\n     * stdio, where the instance is pinned for the connection and owns its guard.\n     */\n    pathGuard?: PathGuard;\n    /**\n     * Store to use instead of constructing one. The HTTP modern leg shares one\n     * store across every per-request instance, so a result a tool externalized\n     * in one POST survives to the follow-up resources/read. Omitted on stdio,\n     * where the pinned instance owns its store for the connection.\n     */\n    resourceStore?: ResourceStore;\n    /**\n     * Pagination snapshots shared by every modern HTTP request. Omitted on\n     * stdio, where the connection-owned context clears its store on close.\n     */\n    pageStore?: PageSnapshotStore;\n    /** The protocol era this instance serves; omitted where the caller does not know. */\n    era?: 'legacy' | 'modern';\n    /**\n     * The resolved HTTP credential, from `--api-key` or `FS_API_KEY`. Lives here\n     * rather than on `ServerOptions` because that object is `PathGuard`'s\n     * constructor argument and is exposed on its public `options` field — a\n     * bearer secret has no business being reachable from a tool handler.\n     */\n    apiKey?: string;\n  },\n): Promise<FilesystemServerContext> {\n  // Only `resources` is declared: `McpServer` advertises `tools` and `prompts`\n  // (with `listChanged: true`) and `completions` from the registrations below,\n  // but never infers `subscribe`.\n  //\n  // `resources.subscribe` stays advertised on both eras: the verb itself is\n  // 2025-only, but the SDK's listen router honors a `subscriptions/listen`\n  // resource filter only while this bit is advertised (dist: `allow(\n  // capabilities?.resources?.subscribe)` on `resourceSubscriptions`). The\n  // strict-capability gate on outbound `notifications/resources/updated`\n  // checks only that `resources` exists. The one exception is a\n  // legacy instance on the HTTP leg (era 'legacy' with a notifier): it serves\n  // one request, registers no subscribe handler (resources.ts, same\n  // predicate) and sends no notification of any kind — there is no stream to\n  // send it on — so neither `subscribe` nor `listChanged` is advertised.\n  // sunset(SEP-2577): removal trigger in docs/adr/002-legacy-protocol-paths-sunset.md.\n  const legacyHttp = extraDeps?.era === 'legacy' && extraDeps.notifier !== undefined;\n  const capabilities = {\n    resources: { subscribe: !legacyHttp, listChanged: !legacyHttp },\n  } satisfies ServerCapabilities;\n\n  const cacheScope: 'private' | 'public' = extraDeps?.apiKey ? 'private' : 'public';\n  const serverConfig: NonNullable<ConstructorParameters<typeof McpServer>[1]> = {\n    capabilities,\n    enforceStrictCapabilities: true,\n    cacheHints: {\n      'tools/list': { ttlMs: 3_600_000, cacheScope },\n      'prompts/list': { ttlMs: 3_600_000, cacheScope },\n      // Always private, never `cacheScope`: this list enumerates the\n      // ResourceStore, so its entries are one caller's externalized tool output\n      // — the same entries whose own read hint is `private` (resources.ts). The\n      // other four lists are the same for every caller and follow the key, and\n      // they are built from frozen module-level arrays that cannot change at\n      // runtime, so an hour is honest: a shorter hint only buys the client a\n      // re-fetch of bytes that cannot have differed, at the cost of the prompt\n      // cache stability the spec asks deterministic ordering to preserve.\n      'resources/list': { ttlMs: 30_000, cacheScope: 'private' },\n      'resources/templates/list': { ttlMs: 3_600_000, cacheScope },\n      'server/discover': { ttlMs: 3_600_000, cacheScope },\n    },\n    // Multi-round-trip `requestState` integrity (protocol revision 2026-07-28):\n    // the codec verifies the HMAC on every retried round before the handler\n    // runs, so a tampered or expired state is rejected as `-32602` rather than\n    // trusted. The decoded `PendingState` reaches handlers via\n    // `ctx.mcpReq.requestState<T>()`.\n    // eslint-disable-next-line @typescript-eslint/unbound-method\n    requestState: { verify: requestStateCodec.verify },\n    // The ResourceStore fires list-changed on every externalization and on\n    // every expiry prune (store.ts), so parallel tools/call on one\n    // connection can send the same notification several times in one tick;\n    // each copy makes the client refetch an unchanged list. The SDK\n    // coalesces same-tick duplicates for methods listed here.\n    // ponytail: same-tick coalescing only — cross-tick bursts (batch\n    // externalizations separated by fs awaits) still fan out; a store-level\n    // debounce is the fix if clients ever report that. The modern HTTP leg\n    // publishes through the ServerEventBus, which this option does not\n    // touch, so it protects the stdio/in-memory leg.\n    debouncedNotificationMethods: ['notifications/resources/list_changed'],\n  };\n\n  serverConfig.instructions =\n    `${INSTRUCTIONS_SUMMARY} ` +\n    `For full guidance, read ${INSTRUCTIONS_URI} or run the get-help prompt.`;\n\n  const implementation: Implementation = {\n    name: 'filesystem-mcp',\n    title: 'Filesystem MCP',\n    version: SERVER_VERSION,\n    ...(SERVER_DESCRIPTION ? { description: SERVER_DESCRIPTION } : {}),\n    ...(SERVER_HOMEPAGE ? { websiteUrl: SERVER_HOMEPAGE } : {}),\n  };\n  const server = new McpServer(implementation, serverConfig);\n  server.server.fallbackNotificationHandler = (notification) => {\n    Logger.debug('Unhandled client notification', { method: notification.method });\n    return Promise.resolve();\n  };\n\n  // A failed send means the connection went away; nothing to recover.\n  const resourceStore =\n    extraDeps?.resourceStore ??\n    new ResourceStore(() => {\n      if (extraDeps?.notifier) {\n        extraDeps.notifier.resourcesChanged();\n        return;\n      }\n      void server.server.sendResourceListChanged().catch((error: unknown) => {\n        Logger.debug('resource list_changed not delivered', { error: String(error) });\n      });\n    });\n  const pageStore = extraDeps?.pageStore ?? new PageSnapshotStore();\n\n  const pathGuard = extraDeps?.pathGuard ?? new PathGuard(options);\n  // Recompute once per guard, keyed on the guard's own state rather than on\n  // whether it was injected — an injected-but-uninitialized guard would\n  // otherwise deny every path. Not unconditional: the HTTP leg shares one guard\n  // across a fresh instance per request, and a repeat recompute would both redo\n  // the root resolution per request and race a concurrent `applyGrant`, which\n  // commits under a mutation lock this call does not take.\n  if (!pathGuard.isInitialized()) await pathGuard.recomputeAllowedDirectories();\n\n  const deps = {\n    server,\n    pathGuard,\n    pageStore,\n    resourceStore,\n    cacheScope,\n    ...(options.readOnly ? { readOnly: true } : {}),\n    ...(extraDeps?.watcherRegistry ? { watcherRegistry: extraDeps.watcherRegistry } : {}),\n    ...(extraDeps?.notifier ? { notifier: extraDeps.notifier } : {}),\n    ...(extraDeps?.era ? { era: extraDeps.era } : {}),\n  };\n\n  const resourceDisposable = registerResources(deps);\n  registerPrompts(deps);\n  registerTools(deps);\n\n  // False when the store is shared across instances and outlives this one.\n  const ownsPages = extraDeps?.pageStore === undefined;\n  let cleanedUp = false;\n  return {\n    mcp: server,\n    pathGuard,\n    disposeRuntimeState() {\n      if (cleanedUp) return;\n      cleanedUp = true;\n      if (ownsPages) pageStore.clear();\n      resourceDisposable.dispose();\n    },\n  };\n}\n"]}

package/dist/tools/batch.d.ts

@@ -15,19 +15,9 @@ export interface BatchResult<T> {
         failed: number;
     };
 }
-type BatchInput<TOverride> = {
+export declare function runOverPaths<TItem extends string | {
     path: string;
-} | {
-    paths: string[];
-} | {
-    files: ({
-        path: string;
-    } & TOverride)[];
-};
-export declare function runOverPaths<TOverride, TPerPath>(args: BatchInput<TOverride>, ctx: ToolCtx, defaultErrorCode: ErrorCode, perPath: (item: {
-    path: string;
-    override?: TOverride;
-}, ctx: ToolCtx) => Promise<TPerPath>): Promise<BatchResult<TPerPath>>;
+}, TPerPath>(items: readonly TItem[], ctx: ToolCtx, defaultErrorCode: ErrorCode, perPath: (item: TItem, ctx: ToolCtx) => Promise<TPerPath>): Promise<BatchResult<TPerPath>>;
 /**
  * A batch where every requested item failed produced no work at all, so it is a
  * failed call - `isError` must say so. Partial failure is deliberately NOT an
@@ -38,5 +28,4 @@ export declare function isTotalFailure(summary: {
     readonly total: number;
     readonly failed: number;
 }): boolean;
-export {};
 //# sourceMappingURL=batch.d.ts.map

package/dist/tools/batch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../../src/tools/batch.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAW,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEhE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAE7F,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5B,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/D;AAED,KAAK,UAAU,CAAC,SAAS,IACvB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,EAAE,CAAA;CAAE,CAAC;AAevF,wBAAsB,YAAY,CAAC,SAAS,EAAE,QAAQ,EACpD,IAAI,EAAE,UAAU,CAAC,SAAS,CAAC,EAC3B,GAAG,EAAE,OAAO,EACZ,gBAAgB,EAAE,SAAS,EAC3B,OAAO,EAAE,CAAC,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,GACzF,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CA8ChC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GAAG,OAAO,CAEV"}
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../../src/tools/batch.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAW,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEhE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAE7F,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5B,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/D;AAED,wBAAsB,YAAY,CAAC,KAAK,SAAS,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,QAAQ,EAClF,KAAK,EAAE,SAAS,KAAK,EAAE,EACvB,GAAG,EAAE,OAAO,EACZ,gBAAgB,EAAE,SAAS,EAC3B,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,GACxD,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CA8ChC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GAAG,OAAO,CAEV"}