Files
Netcatty/domain/externalMcpHttp.ts
T
0ccafbabf7 feat: optional Streamable HTTP for External MCP (#3790)
* feat: add optional Streamable HTTP for External MCP

Serve the existing catalog tools and approval path on a loopback HTTP
endpoint so clients that cannot spawn the stdio launcher, such as Codex
in WSL, can connect with a bearer token. The listener stays off until
the user enables it.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix: close HTTP sockets before stop and export the Codex bearer

Destroy tracked connections before awaiting server.close so disable does not hang on a half-open request. Prefix the Codex snippet with export so the child process receives the token.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix: advertise a real client host and return 413 intact

Wildcard binds no longer copy 127.0.0.1 into client configs; the URL stays empty until a reachable client address is set. Oversized POSTs receive a JSON-RPC 413 before the socket is closed.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix: recheck the bearer token after the HTTP body arrives

A half-open POST already passed auth before readBody. Recheck the live token before dispatch so a rotation during that wait cannot still run a tool.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix: expire idle Streamable HTTP sessions

JSON responses do not keep a socket open, so a client that never sends DELETE used to pin an MCP session until the listener stopped. Sweep sessions that have been idle for 15 minutes, and skip any session with a request still in flight.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix: return 404 when an HTTP session id is unknown

GET and DELETE with a nonempty session id that is no longer active now return 404, matching POST and the Streamable HTTP session contract. A missing session id stays 400.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix: accept bracketed IPv6 origins

Node reports URL.hostname as [::1], so an otherwise valid loopback or wildcard Origin was rejected. Compare the address with the brackets removed.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix: release rejected HTTP handshakes that never open a session

A 406 or 415 from the SDK returns normally before onsessioninitialized. Detach the approval client and close the MCP server when that happens so rejected initializes do not accumulate.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>
2026-10-20 16:39:56 +08:00

59 lines
1.8 KiB
TypeScript

export const EXTERNAL_MCP_HTTP_BEARER_ENV = "NETCATTY_MCP_BEARER_TOKEN";
export const DEFAULT_EXTERNAL_MCP_HTTP_PORT = 47391;
export const DEFAULT_EXTERNAL_MCP_HTTP_HOST = "127.0.0.1";
export const EXTERNAL_MCP_HTTP_PATH = "/mcp";
function formatHostForUrl(host: string): string {
if (host.includes(":") && !host.startsWith("[")) return `[${host}]`;
return host;
}
function isWildcardBind(address: string): boolean {
return address === "0.0.0.0" || address === "::";
}
export function buildExternalMcpHttpUrl(listenAddress: string, port: number, clientHost = ""): string {
const host = isWildcardBind(listenAddress) ? clientHost.trim() : listenAddress;
if (!host || isWildcardBind(host)) return "";
return `http://${formatHostForUrl(host)}:${port}${EXTERNAL_MCP_HTTP_PATH}`;
}
function shellQuote(value: string): string {
return `'${value.replace(/'/g, `'\\''`)}'`;
}
export function buildCodexHttpToml(url: string): string {
return [
"[mcp_servers.netcatty-http]",
`url = ${JSON.stringify(url)}`,
`bearer_token_env_var = ${JSON.stringify(EXTERNAL_MCP_HTTP_BEARER_ENV)}`,
].join("\n");
}
export function buildCodexHttpEnvLine(token: string): string {
return `export ${EXTERNAL_MCP_HTTP_BEARER_ENV}=${shellQuote(token)}`;
}
export function buildClaudeHttpAddCommand(url: string, token: string): string {
return [
"claude mcp add --transport http netcatty-http",
shellQuote(url),
"--header",
shellQuote(`Authorization: Bearer ${token}`),
].join(" ");
}
export function buildGenericHttpMcpJson(url: string, token: string): string {
return JSON.stringify({
mcpServers: {
"netcatty-http": {
type: "http",
url,
headers: {
Authorization: `Bearer ${token}`,
},
},
},
}, null, 2);
}