@mostra/mcp 0.9.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,103 +1,6 @@
1
- import { CallToolResult, McpServerFactory, ToolAnnotations } from "@modelcontextprotocol/server";
2
1
  import { ArtifactProgressParams, MethodDefinition, RequestPolicy } from "@mostra/protocol";
2
+ import { CallToolResult, McpServerFactory, ToolAnnotations } from "@modelcontextprotocol/server";
3
3
  import * as z from "zod";
4
- //#region src/http.d.ts
5
- /** The path the endpoint serves. */
6
- export declare const MCP_PATH = "/mcp";
7
- /** The largest request body the endpoint reads: a whole artifact's files fit (16 MiB). */
8
- export declare const MCP_MAX_BODY_BYTES: number;
9
- /** Failed tokens past this many in {@link GUESS_WINDOW_MS} refuse every token (D97 item 8). */
10
- export declare const GUESS_LIMIT = 30;
11
- /** The guessing limit's window. */
12
- export declare const GUESS_WINDOW_MS = 6e4;
13
- /** How the endpoint is reached and what it requires. */
14
- interface HttpEndpointPolicy extends RequestPolicy {
15
- /** The bearer token every request must carry (`Authorization: Bearer <token>`). */
16
- readonly token: string;
17
- /** The clock; tests move it. */
18
- readonly now?: () => number;
19
- /** Told each refusal, for the server's log (never the token). */
20
- readonly onRefusal?: (refused: {
21
- readonly status: number;
22
- readonly code: string;
23
- }) => void;
24
- /** Told an error the SDK met outside a request's answer. */
25
- readonly onError?: (error: Error) => void;
26
- }
27
- /** The request as the transport received it, before any URL parser normalized it. */
28
- interface RawRequest {
29
- /** The request target exactly as sent (`/mcp`, with any query). */
30
- readonly target: string;
31
- /** Every header in arrival order, so a repeated one is visible. */
32
- readonly headers: readonly (readonly [string, string])[];
33
- }
34
- /** The endpoint. */
35
- interface McpHttpEndpoint {
36
- /** Answers one request. Give `raw` where the transport has it (Node's `rawHeaders`, `req.url`). */
37
- fetch(request: Request, raw?: RawRequest): Promise<Response>;
38
- /** Ends every exchange in flight. */
39
- close(): Promise<void>;
40
- }
41
- /** Builds the endpoint. */
42
- export declare function createHttpEndpoint(factory: McpServerFactory, policy: HttpEndpointPolicy): McpHttpEndpoint;
43
- //#endregion
44
- //#region src/patch.d.ts
45
- /** One exact replacement: `old` must appear exactly once in the file. */
46
- interface TextEdit {
47
- /** Text that appears exactly once in the file; empty to write a new or empty file. */
48
- readonly old: string;
49
- /** What replaces it. */
50
- readonly new: string;
51
- }
52
- /** What `artifact_patch` asks for. */
53
- type PatchRequest = {
54
- readonly path: string;
55
- readonly edits: readonly TextEdit[];
56
- } | {
57
- readonly path?: string;
58
- readonly diff: string;
59
- };
60
- /** One edit or hunk that didn't apply. */
61
- interface PatchRejection {
62
- /** The file it was for. */
63
- readonly path: string;
64
- /** The edit's index in `edits`, from 0. */
65
- readonly edit?: number;
66
- /** The hunk's index in its file's diff, from 0, and its header (`@@ -4,6 +4,7 @@`). */
67
- readonly hunk?: number;
68
- /** The hunk's header, for a hunk. */
69
- readonly header?: string;
70
- /**
71
- * Why: `not-found` (the text isn't in the file), `ambiguous` (it is, more than once),
72
- * `missing` (the file doesn't exist), `exists` (a diff creates a file that already exists),
73
- * `context` (the hunk's lines don't match the file), `binary` (the file isn't UTF-8 text),
74
- * `malformed` (the diff can't be read, or names no file).
75
- */
76
- readonly reason: "not-found" | "ambiguous" | "missing" | "exists" | "context" | "binary" | "malformed";
77
- /** For `ambiguous`: how many times the text appears. */
78
- readonly occurrences?: number;
79
- }
80
- /** The planned change: whole files to write and files to delete. */
81
- interface PlannedPatch {
82
- /** Files to write whole, by path inside the artifact. */
83
- readonly write: readonly {
84
- readonly path: string;
85
- readonly content: string;
86
- }[];
87
- /** Files to delete. */
88
- readonly delete: readonly string[];
89
- }
90
- /** Reads a file of the artifact as bytes, `undefined` when missing. */
91
- type ReadFile = (path: string) => Promise<Uint8Array | undefined>;
92
- /** Plans a patch against the current files: the change, or every rejection. */
93
- export declare function planPatch(request: PatchRequest, read: ReadFile): Promise<{
94
- readonly ok: true;
95
- readonly change: PlannedPatch;
96
- } | {
97
- readonly ok: false;
98
- readonly rejected: PatchRejection[];
99
- }>;
100
- //#endregion
101
4
  //#region src/ports.d.ts
102
5
  /** The Mostra instance the tools act on, through the host protocol (INTERFACES §6). */
103
6
  interface McpInstance {
@@ -202,6 +105,188 @@ interface McpServerOptions {
202
105
  readonly onClient?: (client: McpClientInfo) => void;
203
106
  }
204
107
  //#endregion
108
+ //#region src/docs.d.ts
109
+ /** One topic of the reference. */
110
+ interface DocsTopic {
111
+ /** Its stable slug: `cli`, `telemetry`, a diagnostic code, `guide` or `guide/<name>`. */
112
+ readonly topic: string;
113
+ /** Its title, from the page's first heading. */
114
+ readonly title: string;
115
+ /** Where the docs site serves it. */
116
+ readonly url: string;
117
+ /** Its Markdown file, or a guide topic's first file. */
118
+ readonly file: string;
119
+ /**
120
+ * A guide topic that isn't one Markdown page (a stylesheet, an example): its files, relative to
121
+ * the Skill's `assets/`, each shown as code.
122
+ */
123
+ readonly files?: readonly string[];
124
+ }
125
+ /** Every topic, the pages first and then the codes, sorted. */
126
+ /**
127
+ * Every topic of the reference in `referenceDir` and the Agent Skill in `skillDir`: the pages first,
128
+ * then the guide, then the codes, sorted.
129
+ */
130
+ export declare function docsIndex(referenceDir: string, skillDir: string): DocsTopic[];
131
+ /**
132
+ * The Skill as topics: `guide` (its SKILL.md), `guide/<name>` for each reference,
133
+ * `guide/<file>` for each asset (the baseline stylesheet), and `guide/examples/<name>` for each
134
+ * example, every file of it.
135
+ */
136
+ export declare function guideTopics(dir: string, base: string): DocsTopic[];
137
+ /** How the guide's relative links read through the CLI, before each of its pages. */
138
+ export declare const GUIDE_LINKS: string;
139
+ /** The same for the guide read through `mostra mcp` (D164): topics of `docs_search`, or resources. */
140
+ export declare const MCP_GUIDE_LINKS: string;
141
+ /**
142
+ * A topic's Markdown. A guide page loses its frontmatter and says how its links read (through the
143
+ * CLI by default, or `links`); a guide topic made of files shows each one as code under its path.
144
+ */
145
+ export declare function topicMarkdown(topic: DocsTopic, dir: string, links?: string): string;
146
+ /** The index as Markdown: what `mostra docs` prints without a topic. */
147
+ export declare function indexMarkdown(topics: readonly DocsTopic[]): string;
148
+ /** The topics nearest an unknown one, for its usage error. */
149
+ export declare function nearestTopics(wanted: string, topics: readonly DocsTopic[], count?: number): string[];
150
+ /**
151
+ * The bundled reference as the MCP server's docs (`docs_search`, `mostra://docs/{topic}`): the
152
+ * reference and the Skill in two directories, read once and cached. The CLI gives the copies it
153
+ * ships; the remote server the copies its build carries.
154
+ */
155
+ export declare function fileDocs(options: {
156
+ readonly referenceDir: string;
157
+ readonly skillDir: string;
158
+ readonly links?: string;
159
+ }): McpDocs;
160
+ //#endregion
161
+ //#region src/http.d.ts
162
+ /** The path the endpoint serves. */
163
+ export declare const MCP_PATH = "/mcp";
164
+ /** The largest request body the endpoint reads: a whole artifact's files fit (16 MiB). */
165
+ export declare const MCP_MAX_BODY_BYTES: number;
166
+ /** Failed tokens past this many in {@link GUESS_WINDOW_MS} refuse every token (D97 item 8). */
167
+ export declare const GUESS_LIMIT = 30;
168
+ /** The guessing limit's window. */
169
+ export declare const GUESS_WINDOW_MS = 6e4;
170
+ /** How the endpoint is reached and what it requires. */
171
+ interface HttpEndpointPolicy extends RequestPolicy {
172
+ /** The bearer token every request must carry (`Authorization: Bearer <token>`). */
173
+ readonly token: string;
174
+ /** The clock; tests move it. */
175
+ readonly now?: () => number;
176
+ /** Told each refusal, for the server's log (never the token). */
177
+ readonly onRefusal?: (refused: {
178
+ readonly status: number;
179
+ readonly code: string;
180
+ }) => void;
181
+ /** Told an error the SDK met outside a request's answer. */
182
+ readonly onError?: (error: Error) => void;
183
+ }
184
+ /** The request as the transport received it, before any URL parser normalized it. */
185
+ interface RawRequest {
186
+ /** The request target exactly as sent (`/mcp`, with any query). */
187
+ readonly target: string;
188
+ /** Every header in arrival order, so a repeated one is visible. */
189
+ readonly headers: readonly (readonly [string, string])[];
190
+ }
191
+ /** The endpoint. */
192
+ interface McpHttpEndpoint {
193
+ /** Answers one request. Give `raw` where the transport has it (Node's `rawHeaders`, `req.url`). */
194
+ fetch(request: Request, raw?: RawRequest): Promise<Response>;
195
+ /** Ends every exchange in flight. */
196
+ close(): Promise<void>;
197
+ }
198
+ /** Builds the endpoint. */
199
+ export declare function createHttpEndpoint(factory: McpServerFactory, policy: HttpEndpointPolicy): McpHttpEndpoint;
200
+ /** What an authorization server established about a remote MCP request (INTERFACES §18.8). */
201
+ interface McpAuthorization {
202
+ /** The access token, as presented (never logged). */
203
+ readonly token: string;
204
+ /** The OAuth client the token was issued to. */
205
+ readonly clientId: string;
206
+ /** The token's scopes. */
207
+ readonly scopes: readonly string[];
208
+ /** When the token expires, in seconds since the epoch. */
209
+ readonly expiresAt?: number;
210
+ /** The resource (audience) it was issued for. */
211
+ readonly resource: string;
212
+ /** Whatever the server needs to build the request's ports (its account, its home). */
213
+ readonly subject: Readonly<Record<string, unknown>>;
214
+ }
215
+ /** A remote MCP endpoint: requests whose authorization the caller checked already. */
216
+ interface McpAuthorizedEndpoint {
217
+ /** Serves one request, `authorization` being what the caller established for it. */
218
+ fetch(request: Request, authorization: McpAuthorization): Promise<Response>;
219
+ /** Stops serving: requests in flight end. */
220
+ close(): Promise<void>;
221
+ }
222
+ /**
223
+ * A Streamable HTTP endpoint for a server that authorizes requests itself (the remote server,
224
+ * D164): stateless, for the `2026-07-28` and the 2025 revisions, building each request's MCP
225
+ * server from the ports `optionsFor` gives for its authorization. Host, Origin, the bearer token,
226
+ * its audience and its scope are the caller's to check before; this adds the endpoint's own
227
+ * headers to every answer.
228
+ */
229
+ export declare function createAuthorizedEndpoint(optionsFor: (authorization: McpAuthorization) => McpServerOptions, policy?: {
230
+ readonly onError?: (error: Error) => void;
231
+ }): McpAuthorizedEndpoint;
232
+ //#endregion
233
+ //#region src/patch.d.ts
234
+ /** One exact replacement: `old` must appear exactly once in the file. */
235
+ interface TextEdit {
236
+ /** Text that appears exactly once in the file; empty to write a new or empty file. */
237
+ readonly old: string;
238
+ /** What replaces it. */
239
+ readonly new: string;
240
+ }
241
+ /** What `artifact_patch` asks for. */
242
+ type PatchRequest = {
243
+ readonly path: string;
244
+ readonly edits: readonly TextEdit[];
245
+ } | {
246
+ readonly path?: string;
247
+ readonly diff: string;
248
+ };
249
+ /** One edit or hunk that didn't apply. */
250
+ interface PatchRejection {
251
+ /** The file it was for. */
252
+ readonly path: string;
253
+ /** The edit's index in `edits`, from 0. */
254
+ readonly edit?: number;
255
+ /** The hunk's index in its file's diff, from 0, and its header (`@@ -4,6 +4,7 @@`). */
256
+ readonly hunk?: number;
257
+ /** The hunk's header, for a hunk. */
258
+ readonly header?: string;
259
+ /**
260
+ * Why: `not-found` (the text isn't in the file), `ambiguous` (it is, more than once),
261
+ * `missing` (the file doesn't exist), `exists` (a diff creates a file that already exists),
262
+ * `context` (the hunk's lines don't match the file), `binary` (the file isn't UTF-8 text),
263
+ * `malformed` (the diff can't be read, or names no file).
264
+ */
265
+ readonly reason: "not-found" | "ambiguous" | "missing" | "exists" | "context" | "binary" | "malformed";
266
+ /** For `ambiguous`: how many times the text appears. */
267
+ readonly occurrences?: number;
268
+ }
269
+ /** The planned change: whole files to write and files to delete. */
270
+ interface PlannedPatch {
271
+ /** Files to write whole, by path inside the artifact. */
272
+ readonly write: readonly {
273
+ readonly path: string;
274
+ readonly content: string;
275
+ }[];
276
+ /** Files to delete. */
277
+ readonly delete: readonly string[];
278
+ }
279
+ /** Reads a file of the artifact as bytes, `undefined` when missing. */
280
+ type ReadFile = (path: string) => Promise<Uint8Array | undefined>;
281
+ /** Plans a patch against the current files: the change, or every rejection. */
282
+ export declare function planPatch(request: PatchRequest, read: ReadFile): Promise<{
283
+ readonly ok: true;
284
+ readonly change: PlannedPatch;
285
+ } | {
286
+ readonly ok: false;
287
+ readonly rejected: PatchRejection[];
288
+ }>;
289
+ //#endregion
205
290
  //#region src/search.d.ts
206
291
  /** One hit. */
207
292
  interface DocsHit {
@@ -279,5 +364,5 @@ export declare function slug(title: string | undefined): string;
279
364
  /** The workspace on this computer, rooted at `root` (absolute). */
280
365
  export declare function localWorkspace(root: string): McpWorkspace;
281
366
  //#endregion
282
- export type { DocsHit, DocsTopicSummary, HttpEndpointPolicy, McpBrowser, McpClientInfo, McpDocs, McpHttpEndpoint, McpInstance, McpServerOptions, McpWorkspace, PatchRejection, PatchRequest, PlannedPatch, RawRequest, ReadFile, TextEdit, ToolCall, ToolDefinition, WorkspaceFile };
367
+ export type { DocsHit, DocsTopic, DocsTopicSummary, HttpEndpointPolicy, McpAuthorization, McpAuthorizedEndpoint, McpBrowser, McpClientInfo, McpDocs, McpHttpEndpoint, McpInstance, McpServerOptions, McpWorkspace, PatchRejection, PatchRequest, PlannedPatch, RawRequest, ReadFile, TextEdit, ToolCall, ToolDefinition, WorkspaceFile };
283
368
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","names":[],"sources":["../src/http.ts","../src/patch.ts","../src/ports.ts","../src/search.ts","../src/server.ts","../src/tools.ts","../src/workspace.ts"],"mappings":";;;;;qBAuBa;;qBAGA;;qBAGA;;qBAEA;;UAGI,2BAA2B;;WAEjC;;WAEA;;WAEA,aAAa;aAAoB;aAAyB;;;WAE1D,WAAW,OAAO;;;UAIZ;;WAEN;;WAEA;;;UAIM;;EAEf,MAAM,SAAS,SAAS,MAAM,aAAa,QAAQ;;EAEnD,SAAS;;;wBAmCK,mBACd,SAAS,kBACT,QAAQ,qBACP;;;;UCvFc;;WAEN;;WAEA;;;KAIC;WACG;WAAuB,gBAAgB;;WACvC;WAAwB;;;UAGtB;;WAEN;;WAEA;;WAEA;;WAEA;;;;;;;WAOA;;WASA;;;UAIM;;WAEN;aAA2B;aAAuB;;;WAElD;;;KAIC,YAAY,iBAAiB,QAAQ;;wBAK3B,UACpB,SAAS,cACT,MAAM,WACL;WACY;WAAmB,QAAQ;;WAC3B;WAAoB,UAAU;;;;;UC5D5B;;;;;EAKf,KAAK,GAAG,GAAG,QAAQ,iBAAiB,GAAG,IAAI,QAAQ,IAAI,QAAQ;;;;;EAK/D,WACE,uBACA,WAAW,UAAU;;;UAKR;;WAEN;;WAEA,SAAS;;;UAIH;;WAEN;;;;;EAKT,WAAW;;EAEX,YAAY,4BAA4B;;EAExC,KAAK,aAAa,eAAe,QAAQ;;;;;;EAMzC,MACE,aACA;aAAoB,gBAAgB;aAA0B;MAC7D;aAAmB;aAA4B;;;;UAInC;;WAEN;;WAEA;;WAEA;;;UAIM;;EAEf,mBAAmB;;EAEnB,KAAK;;;UAIU;;;;;EAKf,KAAK,oBAAoB;;;UAIV;;WAEN;;WAEA;;;UAIM;;WAEN,UAAU;;WAEV,WAAW;;WAEX,MAAM;;WAEN,UAAU;;;;;WAKV,kBAAkB,iBAAiB,QAAQ;;WAE3C;;;;;;;WAOA,YAAY,QAAQ;;;;;UCzGd;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;;wBAIK,QAAQ;;wBA0BR,WAAW,MAAM,SAAS,eAAe,iBAAY;;;;qBCnBxD;;wBAQG,mBAAmB;;wBAwFnB,uBAAuB,SAAS,mBAAmB;;;;qBCxFtD,cAAc,EAAE,KAAK;EAAe;EAAY;;;qBAMhD;;UAGI;;WAEN,SAAS;;EAElB,SAAS;;;UAIM,eAAe;;WAErB;;WAEA;;WAEA;;WAEA,OAAO,EAAE,QAAQ;;WAEjB,aAAa;;EAEtB,IAAI,MAAM,OAAO,MAAM,WAAW,QAAQ;;;wBAyT5B,YACd,iBAAiB,iBAAiB,QAAQ,mCAChC;;;;wBC/WI,qBAAqB;;;;;;;;;wBAyBrB,aAAa;;wBAuEb,KAAK;;wBAsGL,eAAe,eAAe"}
1
+ {"version":3,"file":"index.d.ts","names":[],"sources":["../src/ports.ts","../src/docs.ts","../src/http.ts","../src/patch.ts","../src/search.ts","../src/server.ts","../src/tools.ts","../src/workspace.ts"],"mappings":";;;;;UAQiB;;;;;EAKf,KAAK,GAAG,GAAG,QAAQ,iBAAiB,GAAG,IAAI,QAAQ,IAAI,QAAQ;;;;;EAK/D,WACE,uBACA,WAAW,UAAU;;;UAKR;;WAEN;;WAEA,SAAS;;;UAIH;;WAEN;;;;;EAKT,WAAW;;EAEX,YAAY,4BAA4B;;EAExC,KAAK,aAAa,eAAe,QAAQ;;;;;;EAMzC,MACE,aACA;aAAoB,gBAAgB;aAA0B;MAC7D;aAAmB;aAA4B;;;;UAInC;;WAEN;;WAEA;;WAEA;;;UAIM;;EAEf,mBAAmB;;EAEnB,KAAK;;;UAIU;;;;;EAKf,KAAK,oBAAoB;;;UAIV;;WAEN;;WAEA;;;UAIM;;WAEN,UAAU;;WAEV,WAAW;;WAEX,MAAM;;WAEN,UAAU;;;;;WAKV,kBAAkB,iBAAiB,QAAQ;;WAE3C;;;;;;;WAOA,YAAY,QAAQ;;;;;UCvGd;;WAEN;;WAEA;;WAEA;;WAEA;;;;;WAKA;;;;;;;wBAeK,UAAU,sBAAsB,mBAAmB;;;;;;wBAwCnD,YAAY,aAAa,eAAe;;qBA4D3C;;qBAIA;;;;;wBAOG,cAAc,OAAO,WAAW,aAAa;;wBAgB7C,cAAc,iBAAiB;;wBA+B/B,cAAc,gBAAgB,iBAAiB,aAAa;;;;;;wBAqC5D,SAAS;WACd;WACA;WACA;IACP;;;;qBCrNS;;qBAGA;;qBAGA;;qBAEA;;UAGI,2BAA2B;;WAEjC;;WAEA;;WAEA,aAAa;aAAoB;aAAyB;;;WAE1D,WAAW,OAAO;;;UAIZ;;WAEN;;WAEA;;;UAIM;;EAEf,MAAM,SAAS,SAAS,MAAM,aAAa,QAAQ;;EAEnD,SAAS;;;wBAmCK,mBACd,SAAS,kBACT,QAAQ,qBACP;;UA8Fc;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA,SAAS,SAAS;;;UAIZ;;EAEf,MAAM,SAAS,SAAS,eAAe,mBAAmB,QAAQ;;EAElE,SAAS;;;;;;;;;wBAUK,yBACd,aAAa,eAAe,qBAAqB,kBACjD;WAAmB,WAAW,OAAO;IACpC;;;;UCxNc;;WAEN;;WAEA;;;KAIC;WACG;WAAuB,gBAAgB;;WACvC;WAAwB;;;UAGtB;;WAEN;;WAEA;;WAEA;;WAEA;;;;;;;WAOA;;WASA;;;UAIM;;WAEN;aAA2B;aAAuB;;;WAElD;;;KAIC,YAAY,iBAAiB,QAAQ;;wBAK3B,UACpB,SAAS,cACT,MAAM,WACL;WACY;WAAmB,QAAQ;;WAC3B;WAAoB,UAAU;;;;;UC3D5B;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;;wBAIK,QAAQ;;wBA0BR,WAAW,MAAM,SAAS,eAAe,iBAAY;;;;qBCnBxD;;wBAQG,mBAAmB;;wBAwFnB,uBAAuB,SAAS,mBAAmB;;;;qBCxFtD,cAAc,EAAE,KAAK;EAAe;EAAY;;;qBAMhD;;UAGI;;WAEN,SAAS;;EAElB,SAAS;;;UAIM,eAAe;;WAErB;;WAEA;;WAEA;;WAEA,OAAO,EAAE,QAAQ;;WAEjB,aAAa;;EAEtB,IAAI,MAAM,OAAO,MAAM,WAAW,QAAQ;;;wBAyT5B,YACd,iBAAiB,iBAAiB,QAAQ,mCAChC;;;;wBC/WI,qBAAqB;;;;;;;;;wBAyBrB,aAAa;;wBAuEb,KAAK;;wBAsGL,eAAe,eAAe"}