Repository navigation
Expand file tree
/
Copy pathfile-resources.ts
More file actions
250 lines (235 loc) · 8.85 KB
/
Copy pathfile-resources.ts
File metadata and controls
250 lines (235 loc) · 8.85 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
// Files as MCP resources (#297). The server exposes one resource template,
// `file://{+path}`, so a client can read any file inside the allowed
// directories with resources/read and get it back as text or as a base64 blob
// with its MIME type, instead of only through the read tools. A resource is
// read by the client application, which can put it in model context or show it
// to the user, rather than returned inside a tool result the model must relay.
//
// The template has no list callback, on purpose: resources/list stays empty, so
// the server never enumerates the disk. A client reaches a file by building its
// URI from the template (or from a path a tool returned), and every read goes
// through the same validatePath as the tools, so a resource can reach nothing a
// tool cannot: no path outside the allowed directories, and no symlink whose
// target is outside them.
//
// It lives in a module of its own, registered from createServer() with one
// call, so the server factory's tool code is untouched. The factory hands it
// the live allow-list, the roots barrier and the reason a 2026-07-28
// connection with no directories cannot operate, so a read sees the same
// directories, at the same moment, as a tool call would.
import path from "path";
import { fileURLToPath } from "url";
import {
McpServer,
ProtocolError,
ProtocolErrorCode,
ResourceNotFoundError,
ResourceTemplate,
} from "@modelcontextprotocol/server";
import type { ReadResourceResult } from "@modelcontextprotocol/server";
import { FsTimeoutError, validatePath } from "./lib.js";
import { readFileInDirectory } from "./pinned-directory.js";
/** The URI template every file resource matches (RFC 6570 reserved expansion). */
export const FILE_RESOURCE_TEMPLATE = "file://{+path}";
/** MIME types by lowercase extension; anything else is sniffed (see below). */
const MIME_TYPES: Readonly<Record<string, string>> = {
".txt": "text/plain",
".md": "text/markdown",
".csv": "text/csv",
".html": "text/html",
".htm": "text/html",
".css": "text/css",
".js": "text/javascript",
".mjs": "text/javascript",
".ts": "text/typescript",
".json": "application/json",
".xml": "application/xml",
".yaml": "application/yaml",
".yml": "application/yaml",
".svg": "image/svg+xml",
".png": "image/png",
".jpg": "image/jpeg",
".jpeg": "image/jpeg",
".gif": "image/gif",
".webp": "image/webp",
".bmp": "image/bmp",
".ico": "image/x-icon",
".mp3": "audio/mpeg",
".wav": "audio/wav",
".ogg": "audio/ogg",
".flac": "audio/flac",
".mp4": "video/mp4",
".pdf": "application/pdf",
".zip": "application/zip",
".gz": "application/gzip",
};
/** MIME types outside text/* whose content is still text. */
const TEXTUAL_MIME_TYPES = new Set([
"application/json",
"application/xml",
"application/yaml",
"image/svg+xml",
]);
function isTextualMimeType(mimeType: string): boolean {
return mimeType.startsWith("text/") || TEXTUAL_MIME_TYPES.has(mimeType);
}
/** The bytes as UTF-8 text, or undefined when they are not valid UTF-8 text. */
function decodeText(bytes: Buffer): string | undefined {
// A NUL byte is valid UTF-8 but marks binary content in practice.
if (bytes.includes(0)) return undefined;
try {
return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
} catch {
return undefined;
}
}
/**
* The contents of one file resource: text when its type is textual (or, for an
* unknown extension, when its bytes decode as UTF-8), a base64 blob otherwise.
*/
export function fileResourceContents(
uri: string,
filePath: string,
bytes: Buffer,
): ReadResourceResult["contents"][number] {
const known = MIME_TYPES[path.extname(filePath).toLowerCase()];
if (known === undefined || isTextualMimeType(known)) {
const text = decodeText(bytes);
if (text !== undefined) {
return { uri, mimeType: known ?? "text/plain", text };
}
}
return {
uri,
mimeType: known ?? "application/octet-stream",
blob: bytes.toString("base64"),
};
}
/** The errno codes that mean a path does not exist. */
const MISSING_PATH_CODES = new Set(["ENOENT", "ENOTDIR"]);
/**
* Whether `error` says the path does not exist, directly or through its
* cause: validatePath wraps a missing parent's ENOENT in an Error of its own.
*/
function isMissingPathError(error: unknown): boolean {
for (let e = error; e instanceof Error; e = e.cause) {
const code = (e as NodeJS.ErrnoException).code;
if (code !== undefined && MISSING_PATH_CODES.has(code)) return true;
}
return false;
}
/**
* Whether `error` is the filesystem failing (an errno error, or a call that
* timed out) rather than validatePath refusing the path, which it does with a
* plain Error and no errno code.
*/
function isOperationalError(error: unknown): boolean {
return (
error instanceof FsTimeoutError ||
(error instanceof Error &&
(error as NodeJS.ErrnoException).code !== undefined)
);
}
export interface FileResourceContext {
/** The directories reads are confined to, read at the moment of each read. */
allowedDirectories: () => readonly string[];
/**
* The current roots barrier: settles when no roots refresh is pending. It
* is read again after it settles, since a newer refresh can replace it.
*/
rootsSettled: () => Promise<void>;
/** Why the server cannot serve a read at all right now, if it cannot. */
unavailableReason: () => string | undefined;
}
/** Register the `file://{+path}` resource template on `server`. */
export function registerFileResources(
server: McpServer,
context: FileResourceContext,
): void {
server.registerResource(
"file",
new ResourceTemplate(FILE_RESOURCE_TEMPLATE, { list: undefined }),
{
title: "File",
description:
"A file inside the allowed directories, by its absolute file:// URI " +
"(for example file:///home/user/project/README.md). Text files are " +
"returned as text, other files as a base64 blob with their MIME type. " +
"Directories are not resources; use the list_directory tool to find files.",
// A file can change at any time, and its contents belong to this user.
cacheHint: { ttlMs: 0, cacheScope: "private" },
},
async (uri): Promise<ReadResourceResult> => {
// Wait out a pending roots refresh, as tool calls do, so a read is
// checked against the directories that refresh brings in.
let settled: Promise<void>;
do {
settled = context.rootsSettled();
await settled;
} while (settled !== context.rootsSettled());
const unavailable = context.unavailableReason();
if (unavailable !== undefined) {
throw new ProtocolError(ProtocolErrorCode.InvalidParams, unavailable);
}
let requestedPath: string;
try {
requestedPath = fileURLToPath(uri);
} catch (error) {
throw new ProtocolError(
ProtocolErrorCode.InvalidParams,
`Invalid file URI ${uri.href}: ${(error as Error).message}`,
);
}
let validPath: string;
try {
validPath = await validatePath(
requestedPath,
context.allowedDirectories(),
"read",
);
} catch (error) {
// A path that does not exist (a dangling symlink, a missing parent, a
// path beneath a regular file) is a missing resource, so a client can
// recognise it by the URI in the error data.
if (isMissingPathError(error)) {
throw new ResourceNotFoundError(uri.href, (error as Error).message);
}
// The filesystem failed while resolving the path (an I/O error, a
// timeout): the request was fine, so it is the server's error.
if (isOperationalError(error)) {
throw new ProtocolError(
ProtocolErrorCode.InternalError,
`Failed to resolve ${uri.href}: ${(error as Error).message}`,
);
}
// Outside the allowed directories, or a symlink out of them: the
// message says which, as the tools do.
throw new ProtocolError(
ProtocolErrorCode.InvalidParams,
(error as Error).message,
);
}
let bytes: Buffer;
try {
// Anchored to the validated file's directory, as the tools' reads
// are (pinned-directory.ts).
bytes = await readFileInDirectory(validPath);
} catch (error) {
if (isMissingPathError(error)) {
throw new ResourceNotFoundError(uri.href);
}
if ((error as NodeJS.ErrnoException).code === "EISDIR") {
throw new ResourceNotFoundError(
uri.href,
`Not a file: ${uri.href} is a directory; directories are not resources`,
);
}
throw new ProtocolError(
ProtocolErrorCode.InternalError,
`Failed to read ${uri.href}: ${(error as Error).message}`,
);
}
return { contents: [fileResourceContents(uri.href, validPath, bytes)] };
},
);
}