@m-d-b-code/mcp-kit 0.1.1 → 0.2.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/README.md CHANGED
@@ -63,8 +63,13 @@ if (isEntryPoint(import.meta.url)) await runMain(main, log);
63
63
  A `ConfigError` thrown by `main` becomes one log line and exit code 2. `readToken`,
64
64
  `readInteger` and `readOptional` read the project's own variables. `listen` takes an
65
65
  `onShutdown` callback to close stores and timers. `createBridgeServer` takes `maxBodyBytes` for
66
- tools that receive whole documents as arguments, and `legacy: "reject"` to refuse 2025-era clients
67
- when the gateway only speaks `PROTOCOL_VERSION`.
66
+ tools that receive whole documents as arguments, `legacy: "reject"` to refuse 2025-era clients
67
+ when the gateway only speaks `PROTOCOL_VERSION`, and `routes` for extra JSON paths behind the
68
+ same token (an operator's status page, say):
69
+
70
+ ```ts
71
+ createBridgeServer({ token, buildServer, routes: { "/status": () => store.status() } });
72
+ ```
68
73
 
69
74
  ## Gateway side
70
75
 
package/dist/http.d.ts CHANGED
@@ -1,9 +1,11 @@
1
- import { type Server } from "node:http";
1
+ import { type IncomingMessage, type Server } from "node:http";
2
2
  import { createMcpHandler } from "@modelcontextprotocol/server";
3
3
  import { type Logger } from "./log.js";
4
4
  /** Builds the `McpServer` answering one request: the transport is stateless. */
5
5
  export type ServerFactory = Parameters<typeof createMcpHandler>[0];
6
6
  export declare const DEFAULT_MAX_BODY_BYTES: number;
7
+ /** Answers an extra path with a JSON body; a throw becomes a 500 and a log line. */
8
+ export type RouteHandler = (request: IncomingMessage) => unknown;
7
9
  export interface BridgeServerOptions {
8
10
  token: string;
9
11
  buildServer: ServerFactory;
@@ -15,14 +17,20 @@ export interface BridgeServerOptions {
15
17
  * `PROTOCOL_VERSION` is spoken.
16
18
  */
17
19
  legacy?: "stateless" | "reject";
20
+ /**
21
+ * Extra paths behind the same token as `/mcp`, answered with what their handler returns as
22
+ * JSON: an operator's view of the server's own state, for instance. `/mcp` and `/health` cannot
23
+ * be overridden.
24
+ */
25
+ routes?: Record<string, RouteHandler>;
18
26
  log?: Logger;
19
27
  }
20
28
  export declare function sameSecret(presented: string, expected: string): boolean;
21
29
  /**
22
- * `/health` without a token, `/mcp` behind `x-mcp-token`, nothing else. `/health` says nothing
30
+ * `/health` without a token, `/mcp` and the project's `routes` behind `x-mcp-token`, nothing else. `/health` says nothing
23
31
  * about the project's upstreams: their outage must not get a healthy server restarted.
24
32
  */
25
- export declare function createBridgeServer({ token, buildServer, maxBodyBytes, legacy, log, }: BridgeServerOptions): Server;
33
+ export declare function createBridgeServer({ token, buildServer, maxBodyBytes, legacy, routes, log, }: BridgeServerOptions): Server;
26
34
  export interface ListenOptions {
27
35
  host: string;
28
36
  port: number;
package/dist/http.js CHANGED
@@ -49,20 +49,21 @@ async function readBody(request, maxBytes) {
49
49
  }
50
50
  }
51
51
  /**
52
- * `/health` without a token, `/mcp` behind `x-mcp-token`, nothing else. `/health` says nothing
52
+ * `/health` without a token, `/mcp` and the project's `routes` behind `x-mcp-token`, nothing else. `/health` says nothing
53
53
  * about the project's upstreams: their outage must not get a healthy server restarted.
54
54
  */
55
- export function createBridgeServer({ token, buildServer, maxBodyBytes = DEFAULT_MAX_BODY_BYTES, legacy = "stateless", log = loggerFactory()("http"), }) {
55
+ export function createBridgeServer({ token, buildServer, maxBodyBytes = DEFAULT_MAX_BODY_BYTES, legacy = "stateless", routes = {}, log = loggerFactory()("http"), }) {
56
56
  const onerror = (err) => log.error("MCP request failed", err);
57
57
  const mcp = createMcpHandler(buildServer, { legacy, responseMode: "json", onerror });
58
58
  const handler = toNodeHandler(mcp, { onerror });
59
59
  const server = createServer((request, response) => {
60
- const path = (request.url ?? "").split("?")[0];
60
+ const path = (request.url ?? "").split("?")[0] ?? "";
61
61
  if (path === HEALTH_PATH) {
62
62
  send(response, 200, { status: "ok" });
63
63
  return;
64
64
  }
65
- if (path !== MCP_PATH) {
65
+ const route = path !== MCP_PATH && Object.hasOwn(routes, path) ? routes[path] : undefined;
66
+ if (path !== MCP_PATH && !route) {
66
67
  send(response, 404, { error: "Unknown path." });
67
68
  return;
68
69
  }
@@ -71,6 +72,15 @@ export function createBridgeServer({ token, buildServer, maxBodyBytes = DEFAULT_
71
72
  send(response, 401, { error: "Missing or invalid authentication header." });
72
73
  return;
73
74
  }
75
+ if (route) {
76
+ Promise.resolve()
77
+ .then(() => route(request))
78
+ .then((body) => send(response, 200, body), (err) => {
79
+ log.error(`${path} failed`, err);
80
+ send(response, 500, { error: "Internal error." });
81
+ });
82
+ return;
83
+ }
74
84
  readBody(request, maxBodyBytes)
75
85
  .then((body) => handler(request, response, body), (err) => {
76
86
  if (!(err instanceof BodyError))
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@m-d-b-code/mcp-kit",
3
- "version": "0.1.1",
3
+ "version": "0.2.0",
4
4
  "description": "Shared foundation for MCP servers behind a gateway: authenticated stateless HTTP transport, env config, logging and job-run reporting",
5
5
  "keywords": [
6
6
  "mcp",