@donghanh/hono 0.3.3 → 0.3.5

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@donghanh/hono",
3
- "version": "0.3.3",
3
+ "version": "0.3.5",
4
4
  "description": "Hono routes for GPT Store and LLM chat — renderers for ChatGPT and OpenAI-compatible APIs",
5
5
  "license": "MIT",
6
6
  "type": "module",
package/src/mcp.test.ts CHANGED
@@ -259,6 +259,40 @@ describe("mcpRoutes", () => {
259
259
  expect(result.structuredContent.display).toEqual({ x: 1 });
260
260
  });
261
261
 
262
+ test("tools/call: enrichResponse can add fields to structuredContent", async () => {
263
+ const app = mcpRoutes({
264
+ ...baseConfig,
265
+ registry: makeApp({ q: makeOp("q") }),
266
+ executor: async () => ({ v: 1 }),
267
+ enrichResponse: async (structured, opts) => {
268
+ structured.display = `${opts.operationId}:${opts.userId}`;
269
+ },
270
+ });
271
+ const { result } = await rpc(app, "tools/call", { name: "q" });
272
+ expect(result.structuredContent.display).toBe("q:u1");
273
+ expect(result.structuredContent.q).toEqual({ v: 1 });
274
+ });
275
+
276
+ test("tools/call: enrichResponse receives the call arguments", async () => {
277
+ let seen: Record<string, unknown> | undefined;
278
+ const app = mcpRoutes({
279
+ ...baseConfig,
280
+ registry: makeApp({ q: makeOp("q") }),
281
+ enrichResponse: async (_structured, opts) => {
282
+ seen = opts.variables;
283
+ },
284
+ });
285
+ await rpc(app, "tools/call", { name: "q", arguments: { groupId: "g1" } });
286
+ expect(seen?.groupId).toBe("g1");
287
+ });
288
+
289
+ test("GET /mcp → 405 with Allow: POST", async () => {
290
+ const app = mcpRoutes({ ...baseConfig, registry: makeApp({}) });
291
+ const res = await app.request("/mcp");
292
+ expect(res.status).toBe(405);
293
+ expect(res.headers.get("allow")).toBe("POST");
294
+ });
295
+
262
296
  test("unknown tool → error", async () => {
263
297
  const app = mcpRoutes({ ...baseConfig, registry: makeApp({}) });
264
298
  const { error } = await rpc(app, "tools/call", { name: "nope" });
package/src/mcp.ts CHANGED
@@ -37,6 +37,17 @@ export interface McpRoutesConfig {
37
37
  encodeVariables?: (vars: Record<string, unknown>) => string;
38
38
  /** Named widgets. Operation's `widget` config key must match a name here. */
39
39
  widgets?: Record<string, WidgetConfig>;
40
+ /** Hook to enrich `structuredContent` after execution (e.g. inject display text) */
41
+ enrichResponse?: (
42
+ structured: Record<string, unknown>,
43
+ opts: {
44
+ operationId: string;
45
+ data: unknown;
46
+ variables: Record<string, unknown>;
47
+ userId: string | null;
48
+ request: Request;
49
+ },
50
+ ) => Promise<void>;
40
51
  }
41
52
 
42
53
  type JsonRpcRequest = {
@@ -136,6 +147,7 @@ export function mcpRoutes(config: McpRoutesConfig): Hono {
136
147
  serverInfo = { name: "donghanh-mcp", version: "0.1.0" },
137
148
  encodeVariables,
138
149
  widgets = {},
150
+ enrichResponse,
139
151
  } = config;
140
152
 
141
153
  const app = new Hono();
@@ -152,6 +164,12 @@ export function mcpRoutes(config: McpRoutesConfig): Hono {
152
164
  }),
153
165
  );
154
166
 
167
+ // Stateless server: no SSE stream to open
168
+ app.get(
169
+ "/mcp",
170
+ () => new Response(null, { status: 405, headers: { Allow: "POST" } }),
171
+ );
172
+
155
173
  app.post("/mcp", async (c) => {
156
174
  let body: JsonRpcRequest;
157
175
  try {
@@ -290,11 +308,12 @@ export function mcpRoutes(config: McpRoutesConfig): Hono {
290
308
  }
291
309
  }
292
310
 
311
+ const variables = params.arguments ?? {};
293
312
  try {
294
313
  const { data, brief } = await executeOperation({
295
314
  registry,
296
315
  operationId: toolName,
297
- variables: params.arguments ?? {},
316
+ variables,
298
317
  executor,
299
318
  context: { userId, request: c.req.raw },
300
319
  });
@@ -314,6 +333,16 @@ export function mcpRoutes(config: McpRoutesConfig): Hono {
314
333
  structured.display = rendered.display;
315
334
  }
316
335
 
336
+ if (enrichResponse) {
337
+ await enrichResponse(structured, {
338
+ operationId: toolName,
339
+ data,
340
+ variables,
341
+ userId,
342
+ request: c.req.raw,
343
+ });
344
+ }
345
+
317
346
  const meta: Record<string, unknown> = {};
318
347
  if (rendered.context && rendered.context.length > 0) {
319
348
  meta["donghanh/context"] = rendered.context;
@@ -32,7 +32,7 @@ const servers = [{ url: "https://api.example.com" }];
32
32
  const basePath = "/api/gpt";
33
33
 
34
34
  describe("generateOpenApi common", () => {
35
- test("emits 3.1.0 spec with info + servers + bearerAuth + empty schemas", () => {
35
+ test("emits 3.1.0 spec with info + servers + default bearer scheme", () => {
36
36
  const spec = generateOpenApi({
37
37
  registry: registry({ a: makeOp("a") }),
38
38
  info,
@@ -46,7 +46,9 @@ describe("generateOpenApi common", () => {
46
46
  type: "http",
47
47
  scheme: "bearer",
48
48
  });
49
- expect(spec.components.schemas).toEqual({});
49
+ // components.schemas always includes OperationResponse (validator requires object)
50
+ expect(typeof spec.components.schemas).toBe("object");
51
+ expect(spec.components.schemas.OperationResponse).toBeDefined();
50
52
  });
51
53
 
52
54
  test("includeDescription is off by default — no description field", () => {
@@ -106,6 +108,86 @@ describe("generateOpenApi common", () => {
106
108
  expect(s.length).toBeLessThanOrEqual(120);
107
109
  });
108
110
 
111
+ test("emits discovery endpoints by default (listOperations + getOperationDetail)", () => {
112
+ const spec = generateOpenApi({
113
+ registry: registry({ a: makeOp("a") }),
114
+ info,
115
+ servers,
116
+ basePath,
117
+ }) as any;
118
+ expect(spec.paths["/api/gpt/operations"].get.operationId).toBe(
119
+ "listOperations",
120
+ );
121
+ expect(spec.paths["/api/gpt/operations/{name}"].get.operationId).toBe(
122
+ "getOperationDetail",
123
+ );
124
+ expect(spec.paths["/api/gpt/operations"].get.security).toEqual([]);
125
+ expect(spec.paths["/api/gpt/operations/{name}"].get.security).toEqual([]);
126
+ });
127
+
128
+ test("includeDiscoveryEndpoints: false omits them", () => {
129
+ const spec = generateOpenApi({
130
+ registry: registry({ a: makeOp("a") }),
131
+ info,
132
+ servers,
133
+ basePath,
134
+ includeDiscoveryEndpoints: false,
135
+ }) as any;
136
+ expect(spec.paths["/api/gpt/operations"]).toBeUndefined();
137
+ expect(spec.paths["/api/gpt/operations/{name}"]).toBeUndefined();
138
+ });
139
+
140
+ test("emits OperationResponse component schema referenced by paths", () => {
141
+ const spec = generateOpenApi({
142
+ registry: registry({ a: makeOp("a") }),
143
+ info,
144
+ servers,
145
+ basePath,
146
+ pathStyle: "per-op",
147
+ }) as any;
148
+ expect(spec.components.schemas.OperationResponse.type).toBe("object");
149
+ expect(
150
+ spec.components.schemas.OperationResponse.properties.suggestedActions,
151
+ ).toBeDefined();
152
+ expect(
153
+ spec.components.schemas.OperationResponse.properties.nextSteps,
154
+ ).toBeDefined();
155
+ expect(
156
+ spec.paths["/api/gpt/query/a"].get.responses["200"].content[
157
+ "application/json"
158
+ ].schema.$ref,
159
+ ).toBe("#/components/schemas/OperationResponse");
160
+ });
161
+
162
+ test("securityScheme override for oauth2 flow", () => {
163
+ const spec = generateOpenApi({
164
+ registry: registry({ a: makeOp("a") }),
165
+ info,
166
+ servers,
167
+ basePath,
168
+ securityScheme: {
169
+ type: "oauth2",
170
+ flows: {
171
+ authorizationCode: {
172
+ authorizationUrl: "https://example.com/oauth/authorize",
173
+ tokenUrl: "https://example.com/oauth/token",
174
+ scopes: {},
175
+ },
176
+ },
177
+ },
178
+ }) as any;
179
+ expect(spec.components.securitySchemes.bearerAuth).toEqual({
180
+ type: "oauth2",
181
+ flows: {
182
+ authorizationCode: {
183
+ authorizationUrl: "https://example.com/oauth/authorize",
184
+ tokenUrl: "https://example.com/oauth/token",
185
+ scopes: {},
186
+ },
187
+ },
188
+ });
189
+ });
190
+
109
191
  test("custom bearerSchemeName", () => {
110
192
  const spec = generateOpenApi({
111
193
  registry: registry({ a: makeOp("a") }),
@@ -134,6 +216,7 @@ describe("generateOpenApi pathStyle: 'per-op'", () => {
134
216
  const spec = generateOpenApi({
135
217
  ...opts,
136
218
  registry: registry({ a: makeOp("a", { auth: "required" }) }),
219
+ includeDiscoveryEndpoints: false,
137
220
  }) as any;
138
221
  expect(Object.keys(spec.paths)).toEqual(["/api/gpt/query/a"]);
139
222
  expect(spec.paths["/api/gpt/query/a"].get.security).toEqual([
@@ -145,6 +228,7 @@ describe("generateOpenApi pathStyle: 'per-op'", () => {
145
228
  const spec = generateOpenApi({
146
229
  ...opts,
147
230
  registry: registry({ a: makeOp("a", { auth: "none" }) }),
231
+ includeDiscoveryEndpoints: false,
148
232
  }) as any;
149
233
  expect(Object.keys(spec.paths)).toEqual(["/api/gpt/public/query/a"]);
150
234
  expect(spec.paths["/api/gpt/public/query/a"].get.security).toEqual([]);
@@ -154,6 +238,7 @@ describe("generateOpenApi pathStyle: 'per-op'", () => {
154
238
  const spec = generateOpenApi({
155
239
  ...opts,
156
240
  registry: registry({ a: makeOp("a", { auth: "optional" }) }),
241
+ includeDiscoveryEndpoints: false,
157
242
  }) as any;
158
243
  const ks = Object.keys(spec.paths).sort();
159
244
  expect(ks).toEqual(["/api/gpt/public/query/a", "/api/gpt/query/a"]);
@@ -190,6 +275,7 @@ describe("generateOpenApi pathStyle: 'parametric' (default)", () => {
190
275
  info,
191
276
  servers,
192
277
  basePath,
278
+ includeDiscoveryEndpoints: false,
193
279
  }) as any;
194
280
  const ks = Object.keys(spec.paths);
195
281
  expect(ks).toEqual(["/api/gpt/query/{operation}"]);
@@ -209,6 +295,7 @@ describe("generateOpenApi pathStyle: 'parametric' (default)", () => {
209
295
  info,
210
296
  servers,
211
297
  basePath,
298
+ includeDiscoveryEndpoints: false,
212
299
  }) as any;
213
300
  const ks = Object.keys(spec.paths).sort();
214
301
  expect(ks).toEqual([
package/src/openapi.ts CHANGED
@@ -17,8 +17,32 @@ export interface GenerateOpenApiConfig {
17
17
  servers: OpenApiServer[];
18
18
  /** Mount path prefix, e.g. "/api/gpt". Omit trailing slash. Defaults to "". */
19
19
  basePath?: string;
20
- /** Name of the bearer security scheme. Defaults to "bearerAuth". */
20
+ /** Name of the security scheme entry under components.securitySchemes. Defaults to "bearerAuth". */
21
21
  bearerSchemeName?: string;
22
+ /**
23
+ * Full security scheme object to place under components.securitySchemes.
24
+ * Defaults to `{ type: "http", scheme: "bearer" }`. Pass an oauth2 flow
25
+ * object to match ChatGPT Custom GPT OAuth requirements:
26
+ *
27
+ * securityScheme: {
28
+ * type: "oauth2",
29
+ * flows: {
30
+ * authorizationCode: {
31
+ * authorizationUrl: "https://example.com/oauth/authorize",
32
+ * tokenUrl: "https://example.com/oauth/token",
33
+ * scopes: {},
34
+ * },
35
+ * },
36
+ * }
37
+ */
38
+ securityScheme?: Record<string, unknown>;
39
+ /**
40
+ * Include the discovery endpoints (`GET /operations` and
41
+ * `GET /operations/{name}`) in the generated spec. Default true — the
42
+ * GPT relies on these to learn available operations and their input
43
+ * schemas before invoking one.
44
+ */
45
+ includeDiscoveryEndpoints?: boolean;
22
46
  /** When true, adds an info note about the $variables encoding (default true). */
23
47
  describeVariables?: boolean;
24
48
  /**
@@ -86,6 +110,8 @@ export function generateOpenApi(config: GenerateOpenApiConfig): object {
86
110
  servers,
87
111
  basePath = "",
88
112
  bearerSchemeName = "bearerAuth",
113
+ securityScheme = { type: "http", scheme: "bearer" },
114
+ includeDiscoveryEndpoints = true,
89
115
  describeVariables = true,
90
116
  includeDescription = false,
91
117
  maxDescriptionLength = 300,
@@ -129,21 +155,7 @@ export function generateOpenApi(config: GenerateOpenApiConfig): object {
129
155
  description: "Successful response.",
130
156
  content: {
131
157
  "application/json": {
132
- schema: {
133
- type: "object",
134
- properties: {
135
- data: { type: "object" },
136
- suggestedActions: {
137
- type: "array",
138
- items: { type: "object" },
139
- },
140
- nextSteps: { type: "string" },
141
- operations: {
142
- type: "array",
143
- items: { type: "object" },
144
- },
145
- },
146
- },
158
+ schema: { $ref: "#/components/schemas/OperationResponse" },
147
159
  },
148
160
  },
149
161
  },
@@ -151,19 +163,7 @@ export function generateOpenApi(config: GenerateOpenApiConfig): object {
151
163
  description: "Validation or execution error.",
152
164
  content: {
153
165
  "application/json": {
154
- schema: {
155
- type: "object",
156
- properties: {
157
- errors: {
158
- type: "array",
159
- items: {
160
- type: "object",
161
- properties: { message: { type: "string" } },
162
- },
163
- },
164
- operationDetail: { type: "object" },
165
- },
166
- },
166
+ schema: { $ref: "#/components/schemas/OperationResponse" },
167
167
  },
168
168
  },
169
169
  },
@@ -243,21 +243,224 @@ export function generateOpenApi(config: GenerateOpenApiConfig): object {
243
243
  }
244
244
  }
245
245
 
246
+ if (includeDiscoveryEndpoints) {
247
+ emitDiscoveryEndpoints(paths, basePath, noSec, successResponse);
248
+ }
249
+
246
250
  return {
247
251
  openapi: "3.1.0",
248
252
  info,
249
253
  servers,
250
254
  paths,
251
255
  components: {
252
- schemas: {},
256
+ schemas: {
257
+ OperationResponse: operationResponseSchema,
258
+ },
253
259
  securitySchemes: {
254
- [bearerSchemeName]: {
255
- type: "http",
256
- scheme: "bearer",
260
+ [bearerSchemeName]: securityScheme,
261
+ },
262
+ },
263
+ };
264
+ }
265
+
266
+ const operationResponseSchema = {
267
+ type: "object",
268
+ properties: {
269
+ data: { type: "object", description: "Operation result data" },
270
+ errors: {
271
+ type: "array",
272
+ description: "Included on error responses.",
273
+ items: {
274
+ type: "object",
275
+ properties: { message: { type: "string" } },
276
+ },
277
+ },
278
+ operations: {
279
+ type: "array",
280
+ description:
281
+ "All available operations (always present in every response).",
282
+ items: {
283
+ type: "object",
284
+ properties: {
285
+ id: { type: "string" },
286
+ type: { type: "string", enum: ["query", "mutation"] },
287
+ description: { type: "string" },
288
+ auth: { type: "string", enum: ["none", "optional", "required"] },
289
+ },
290
+ },
291
+ },
292
+ suggestedActions: {
293
+ type: "array",
294
+ description:
295
+ "Context-aware suggested next operations with pre-filled variables.",
296
+ items: {
297
+ type: "object",
298
+ properties: {
299
+ id: { type: "string" },
300
+ type: { type: "string", enum: ["query", "mutation"] },
301
+ description: { type: "string" },
302
+ variables: { type: "object" },
303
+ $variables: {
304
+ type: "string",
305
+ description: "Variables pre-encoded as a string, ready to reuse.",
306
+ },
307
+ input: {
308
+ type: "object",
309
+ description: "JSON Schema for this operation's variables",
310
+ },
257
311
  },
258
312
  },
259
313
  },
314
+ display: {
315
+ type: "string",
316
+ description:
317
+ "Pre-rendered text in the user's locale. Suggested wording — adapt tone freely but keep amounts and names accurate.",
318
+ },
319
+ nextSteps: {
320
+ type: "string",
321
+ description:
322
+ "Contextual instructions for the assistant. Follow these exactly.",
323
+ },
324
+ operationDetail: {
325
+ type: "object",
326
+ description:
327
+ "Included on error responses. Contains the operation's input schema and instruction so you can fix your request and retry.",
328
+ properties: {
329
+ instruction: { type: "string" },
330
+ input: { type: "object" },
331
+ },
332
+ },
333
+ responseSchema: {
334
+ type: "object",
335
+ description:
336
+ "JSON Schema for the response data. Included on the start response when configured.",
337
+ },
338
+ },
339
+ };
340
+
341
+ function emitDiscoveryEndpoints(
342
+ paths: Record<string, PathItem>,
343
+ basePath: string,
344
+ noSec: Sec,
345
+ successResponse: Record<string, unknown>,
346
+ ): void {
347
+ paths[`${basePath}/operations`] = {
348
+ get: {
349
+ operationId: "listOperations",
350
+ summary: "Discover available operations",
351
+ security: noSec,
352
+ parameters: [
353
+ {
354
+ name: "search",
355
+ in: "query",
356
+ required: false,
357
+ description: "Filter operations by keyword in id or description.",
358
+ schema: { type: "string" },
359
+ },
360
+ {
361
+ name: "type",
362
+ in: "query",
363
+ required: false,
364
+ description: "Filter by operation type.",
365
+ schema: { type: "string", enum: ["query", "mutation"] },
366
+ },
367
+ ],
368
+ responses: {
369
+ "200": {
370
+ description: "List of available operations",
371
+ content: {
372
+ "application/json": {
373
+ schema: {
374
+ type: "object",
375
+ properties: {
376
+ operations: {
377
+ type: "array",
378
+ items: {
379
+ type: "object",
380
+ properties: {
381
+ id: { type: "string" },
382
+ type: {
383
+ type: "string",
384
+ enum: ["query", "mutation"],
385
+ },
386
+ description: { type: "string" },
387
+ auth: {
388
+ type: "string",
389
+ enum: ["none", "optional", "required"],
390
+ },
391
+ },
392
+ },
393
+ },
394
+ },
395
+ },
396
+ },
397
+ },
398
+ },
399
+ },
400
+ } as Operation,
401
+ };
402
+
403
+ paths[`${basePath}/operations/{name}`] = {
404
+ get: {
405
+ operationId: "getOperationDetail",
406
+ summary: "Get full details for a specific operation",
407
+ security: noSec,
408
+ parameters: [
409
+ {
410
+ name: "name",
411
+ in: "path",
412
+ required: true,
413
+ description: "Operation slug.",
414
+ schema: { type: "string" },
415
+ },
416
+ ],
417
+ responses: {
418
+ "200": {
419
+ description: "Operation detail",
420
+ content: {
421
+ "application/json": {
422
+ schema: {
423
+ type: "object",
424
+ properties: {
425
+ id: { type: "string" },
426
+ type: { type: "string", enum: ["query", "mutation"] },
427
+ description: { type: "string" },
428
+ instruction: { type: "string" },
429
+ input: { type: "object" },
430
+ response: { type: "object" },
431
+ auth: {
432
+ type: "string",
433
+ enum: ["none", "optional", "required"],
434
+ },
435
+ operations: {
436
+ type: "array",
437
+ description:
438
+ "Present when includeOperationsInDetail is enabled on gptRoutes.",
439
+ items: {
440
+ type: "object",
441
+ properties: {
442
+ id: { type: "string" },
443
+ type: { type: "string", enum: ["query", "mutation"] },
444
+ description: { type: "string" },
445
+ auth: {
446
+ type: "string",
447
+ enum: ["none", "optional", "required"],
448
+ },
449
+ },
450
+ },
451
+ },
452
+ },
453
+ },
454
+ },
455
+ },
456
+ },
457
+ "404": {
458
+ description: "Unknown operation",
459
+ },
460
+ },
461
+ } as Operation,
260
462
  };
463
+ void successResponse;
261
464
  }
262
465
 
263
466
  function emitParametric(