@softov/ahpc 0.1.0 → 0.3.0

package/dist/src/mcp/http.d.ts

@@ -0,0 +1,34 @@
+import type { HostConnection } from '../ahp/connection.js';
+export interface ServeOptions {
+    host: string;
+    port: number;
+    name: string;
+    version: string;
+    /**
+     * A bearer token every request must carry, if any.
+     *
+     * Absent means anybody who can reach the port can drive every session on the
+     * host, which is why `--serve-host` defaults to the loopback address. A
+     * token is what makes binding anywhere else defensible.
+     */
+    token?: string;
+    /**
+     * Browser origins allowed to reach this, beyond its own.
+     *
+     * Empty is the safe default and the usual answer: a shell script, a webhook
+     * and an MCP client send no `Origin` at all, so nothing legitimate is turned
+     * away by allowing none. This is for a page somebody serves themselves.
+     */
+    origins?: readonly string[];
+    /** The opt-in tool groups to serve, beyond the core table. */
+    groups?: readonly string[];
+    onProblem?(said: string): void;
+}
+/** What this is listening on, and how to stop it. */
+export interface Serving {
+    host: string;
+    port: number;
+    close(): Promise<void>;
+}
+/** Start listening. Answers once the socket is up. */
+export declare function serve(host: HostConnection, options: ServeOptions): Promise<Serving>;

package/dist/src/mcp/http.js

@@ -0,0 +1,247 @@
+/*
+ * The same tools over a socket, twice.
+ *
+ * `POST /mcp` is MCP's streamable HTTP transport, which for a tools-only
+ * server is a JSON-RPC request in and a JSON-RPC response out. `POST
+ * /api/<tool>` is the same tool with the arguments as the body and the answer
+ * as the body, for everything that is not an MCP client - a shell script, a
+ * webhook, a program in another language. `GET /api` lists what there is.
+ *
+ * One process, one connection to the host, however many callers. That is the
+ * difference from `stdio`, and the reason both exist: stdio is owned by the
+ * client that launched it, this is shared and outlives any of them.
+ */
+import { createServer } from 'node:http';
+import { SPOKEN, answer, call, listing } from './serve.js';
+/** How much of a request body is read before it is refused, in bytes. */
+const LIMIT = 1_000_000;
+const body = async (request) => {
+    let read = '';
+    for await (const chunk of request) {
+        read += String(chunk);
+        if (read.length > LIMIT)
+            throw new Error('That request is too big.');
+    }
+    return read;
+};
+/**
+ * Answer a request with a stream rather than one object.
+ *
+ * The transport allows either, and this is the branch that lets anything be
+ * said before the result: notifications go out as they happen and the response
+ * is the last event, after which the stream closes. Only opened where the
+ * caller asked for progress, because a stream is worse for everybody else -
+ * more to parse, and a connection held open for a request that answers at once.
+ */
+const stream = (response) => {
+    response.writeHead(200, {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-cache, no-transform',
+        connection: 'keep-alive',
+    });
+    const event = (value) => { response.write(`data: ${JSON.stringify(value)}\n\n`); };
+    return {
+        event,
+        end: (value) => { event(value); response.end(); },
+    };
+};
+/**
+ * Whether this request asked to be told what is happening while it waits.
+ *
+ * A `progressToken` in `_meta`, which is the only way a caller asks. Read here
+ * rather than inside `answer`, because the decision it drives - a stream or an
+ * object - has to be made before a single byte of the response is written.
+ */
+const wantsProgress = (message) => {
+    const params = message.params;
+    const token = params?._meta?.progressToken;
+    return typeof token === 'string' || typeof token === 'number';
+};
+const send = (response, code, value) => {
+    const text = JSON.stringify(value);
+    response.writeHead(code, {
+        'content-type': 'application/json',
+        'content-length': String(Buffer.byteLength(text)),
+    });
+    response.end(text);
+};
+/**
+ * Whether a request carries the token, where one was set.
+ *
+ * `Authorization: Bearer <token>`, which is what MCP's own HTTP transport
+ * says, and what every client that speaks it already sends.
+ */
+const allowed = (request, token) => {
+    if (token === undefined)
+        return true;
+    const said = request.headers.authorization;
+    return typeof said === 'string' && said.trim() === `Bearer ${token}`;
+};
+/**
+ * Whether a browser may talk to this.
+ *
+ * The transport says a server **MUST** validate `Origin` to stop DNS
+ * rebinding, and the reason it says so is that binding to loopback is not the
+ * protection it looks like: a page on any website can POST to
+ * `http://127.0.0.1:7431` from inside the browser of the person running this,
+ * and the request arrives from their own machine looking exactly like theirs.
+ * Without this, opening a tab would be enough to drive every session on the
+ * host.
+ *
+ * No header at all is allowed. A browser always sends one on a request like
+ * these; a program does not, and refusing those would refuse every real
+ * caller to guard against a thing that cannot happen.
+ */
+const sameOrigin = (request, url, extra) => {
+    const said = request.headers.origin;
+    if (typeof said !== 'string' || said === '')
+        return true;
+    if (extra.includes(said))
+        return true;
+    try {
+        const from = new URL(said);
+        // The host and port this request came in on, whatever name was used to
+        // reach it - `localhost` and `127.0.0.1` are the same server and a person
+        // typing either should not be told no.
+        return from.host === url.host;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Whether this can speak the version the client says it is using.
+ *
+ * The transport says an invalid or unsupported `MCP-Protocol-Version` **MUST**
+ * be a 400. Absent is not unsupported: the same paragraph says to assume
+ * `2025-03-26` where there is no header, which is a client from before it
+ * existed.
+ */
+const speakable = (request) => {
+    const said = request.headers['mcp-protocol-version'];
+    if (said === undefined)
+        return true;
+    return typeof said === 'string' && SPOKEN.includes(said);
+};
+/** Start listening. Answers once the socket is up. */
+export async function serve(host, options) {
+    const server = createServer((request, response) => {
+        void (async () => {
+            try {
+                const url = new URL(request.url ?? '/', `http://${request.headers.host ?? 'localhost'}`);
+                const path = url.pathname.replace(/\/+$/, '') || '/';
+                if (!sameOrigin(request, url, options.origins ?? [])) {
+                    // 403 rather than 401: a token would not make this request
+                    // acceptable, so inviting one would be the wrong thing to say.
+                    send(response, 403, { error: `This server does not serve requests from ${String(request.headers.origin)}.` });
+                    return;
+                }
+                if (!speakable(request)) {
+                    send(response, 400, {
+                        error: `This server does not speak MCP ${String(request.headers['mcp-protocol-version'])}. It speaks ${SPOKEN.join(', ')}.`,
+                    });
+                    return;
+                }
+                if (!allowed(request, options.token)) {
+                    send(response, 401, { error: 'This server needs a bearer token.' });
+                    return;
+                }
+                // What is here, for somebody who has just started it and wants to know
+                // what to call. Every tool with its schema, which is also what an MCP
+                // client gets from `tools/list`.
+                if (request.method === 'GET' && (path === '/api' || path === '/')) {
+                    send(response, 200, listing(options.groups));
+                    return;
+                }
+                if (path === '/mcp') {
+                    if (request.method !== 'POST') {
+                        // No SSE stream: this server sends nothing a client did not ask
+                        // for, so there is nothing for a GET to hold open.
+                        send(response, 405, { error: 'POST a JSON-RPC message here.' });
+                        return;
+                    }
+                    let message;
+                    try {
+                        message = JSON.parse(await body(request));
+                    }
+                    catch {
+                        send(response, 400, { jsonrpc: '2.0', id: null, error: { code: -32700, message: 'That is not JSON.' } });
+                        return;
+                    }
+                    if (wantsProgress(message)) {
+                        const open = stream(response);
+                        const reply = await answer(host, message, {
+                            ...options,
+                            notify: (notification) => open.event({ jsonrpc: '2.0', ...notification }),
+                        });
+                        // A notification that also carried a progress token has nothing to
+                        // end the stream with, so it is closed rather than left open on a
+                        // response that is never coming.
+                        if (reply === undefined) {
+                            response.end();
+                            return;
+                        }
+                        open.end(reply);
+                        return;
+                    }
+                    const reply = await answer(host, message, options);
+                    // A notification is answered with 202 and no body, which is what the
+                    // transport says and what a client waiting on one would hang over.
+                    if (reply === undefined) {
+                        response.writeHead(202);
+                        response.end();
+                        return;
+                    }
+                    send(response, 200, reply);
+                    return;
+                }
+                if (path.startsWith('/api/')) {
+                    if (request.method !== 'POST') {
+                        send(response, 405, { error: 'POST to call a tool.' });
+                        return;
+                    }
+                    const name = path.slice('/api/'.length);
+                    const raw = await body(request);
+                    let input = {};
+                    if (raw.trim() !== '') {
+                        try {
+                            input = JSON.parse(raw);
+                        }
+                        catch {
+                            send(response, 400, { error: 'That is not JSON.' });
+                            return;
+                        }
+                    }
+                    const result = await call(host, name, input, undefined, options.groups);
+                    // Shaped for a program rather than for a model: the answer itself,
+                    // or the refusal as an error, without MCP's content envelope around
+                    // it. A caller that wants the envelope has `/mcp`.
+                    if (result.isError === true) {
+                        send(response, 400, { error: result.content?.[0]?.text ?? 'That did not work.' });
+                        return;
+                    }
+                    send(response, 200, result.structuredContent ?? {});
+                    return;
+                }
+                send(response, 404, { error: `Nothing at ${path}. Try GET /api.` });
+            }
+            catch (error) {
+                options.onProblem?.(error instanceof Error ? error.message : String(error));
+                if (!response.headersSent)
+                    send(response, 500, { error: 'Something went wrong here.' });
+                else
+                    response.end();
+            }
+        })();
+    });
+    await new Promise((up, fail) => {
+        server.once('error', fail);
+        server.listen(options.port, options.host, () => { server.off('error', fail); up(); });
+    });
+    const found = server.address();
+    return {
+        host: typeof found === 'object' && found !== null ? found.address : options.host,
+        port: typeof found === 'object' && found !== null ? found.port : options.port,
+        close: () => new Promise((done) => { server.close(() => done()); }),
+    };
+}

package/dist/src/mcp/serve.d.ts

@@ -0,0 +1,96 @@
+import type { HostConnection } from '../ahp/connection.js';
+/** The newest version of MCP this speaks, and what it answers an unknown one with. */
+export declare const PROTOCOL = "2025-06-18";
+/**
+ * Every version this will serve, newest first.
+ *
+ * Both of these describe the same tools, and this server uses nothing either
+ * of them added or removed - no sessions, no resources, no sampling - so
+ * refusing the older one would be refusing a client for a difference that
+ * cannot reach it. `2024-11-05` is *not* here: its HTTP transport is a
+ * different shape, with an `endpoint` event and a second URL.
+ */
+export declare const SPOKEN: readonly string[];
+/**
+ * What this server calls itself.
+ *
+ * MCP requires a version where AHP's `clientInfo` does not. Read from the
+ * manifest rather than written here: the literal that used to be here said
+ * 0.1 while the package said 0.2, within a day of being written.
+ */
+export declare const SERVER: {
+    name: string;
+    version: string;
+};
+/** A JSON-RPC request or notification, as far as this needs to read one. */
+export interface Incoming {
+    jsonrpc?: unknown;
+    id?: number | string | null;
+    method?: unknown;
+    params?: unknown;
+}
+/**
+ * One progress notification, as `notifications/progress` puts it on the wire.
+ *
+ * `progress` MUST increase on every one, `total` is left out because an
+ * agent's reply has no length known in advance, and `message` is what a person
+ * reads - which is the tool name a session stopped on, or the host's own words
+ * for what it is doing.
+ */
+export interface Progress {
+    progressToken: string | number;
+    progress: number;
+    message?: string;
+}
+/** Somewhere to put progress while a tool runs, or nothing where nobody asked. */
+export type Report = ((said: string) => void) | undefined;
+/** What goes back, or nothing at all where the message was a notification. */
+export type Outgoing = {
+    jsonrpc: '2.0';
+    id: number | string | null;
+} & ({
+    result: unknown;
+    error?: never;
+} | {
+    error: {
+        code: number;
+        message: string;
+    };
+    result?: never;
+});
+/** The tools, in the shape `tools/list` puts them on the wire. */
+export declare const listing: (groups?: readonly string[]) => unknown;
+/**
+ * Run one tool and shape the answer the way `tools/call` wants it.
+ *
+ * A tool that throws is *not* a protocol error. MCP has `isError` on the
+ * result for exactly this: the call reached the tool and the tool said no,
+ * which a model can read and act on, where a JSON-RPC error is a transport
+ * fault it can only give up over. So a refusal from the host - a session that
+ * is gone, a directory it does not serve - comes back as content.
+ */
+export declare function call(host: HostConnection, name: string, input: unknown, report?: Report, groups?: readonly string[]): Promise<unknown>;
+/**
+ * Answer one message.
+ *
+ * `undefined` where there is nothing to send back, which is a notification -
+ * and answering one anyway is a protocol error on this end, not a courtesy.
+ */
+export declare function answer(host: HostConnection, message: Incoming, options: {
+    name: string;
+    version: string;
+    /** The opt-in tool groups this server was started with, if any. */
+    groups?: readonly string[];
+    /**
+     * Somewhere to send a notification while this is being answered.
+     *
+     * Given by a transport that has one: stdio always does, and HTTP does only
+     * once it has decided to answer with a stream. Absent means there is
+     * nowhere to say anything until the result, which is the ordinary case and
+     * why every progress path here is optional.
+     */
+    notify?(notification: {
+        method: string;
+        params: unknown;
+    }): void;
+}): Promise<Outgoing | undefined>;

package/dist/src/mcp/serve.js

@@ -0,0 +1,169 @@
+/*
+ * MCP, spoken directly.
+ *
+ * The protocol a tools-only server has to answer is small: `initialize`, an
+ * `initialized` notification with no reply, `tools/list`, `tools/call`, and
+ * `ping`. All of it is JSON-RPC 2.0, which this client already reads and
+ * writes for AHP. An SDK for those five would be a dependency the published
+ * CLI carries into every install to save a hundred lines - the same trade
+ * `flags.ts` refuses for argv.
+ *
+ * What is deliberately not here: prompts, resources, sampling, roots and
+ * subscriptions. A server that advertises no capability for them is not
+ * obliged to answer them, and a caller that asks is told the method is not
+ * there, which is the truth.
+ */
+import { named, served } from './tools.js';
+import { version } from '../version.js';
+/** The newest version of MCP this speaks, and what it answers an unknown one with. */
+export const PROTOCOL = '2025-06-18';
+/**
+ * Every version this will serve, newest first.
+ *
+ * Both of these describe the same tools, and this server uses nothing either
+ * of them added or removed - no sessions, no resources, no sampling - so
+ * refusing the older one would be refusing a client for a difference that
+ * cannot reach it. `2024-11-05` is *not* here: its HTTP transport is a
+ * different shape, with an `endpoint` event and a second URL.
+ */
+export const SPOKEN = ['2025-06-18', '2025-03-26'];
+/**
+ * What this server calls itself.
+ *
+ * MCP requires a version where AHP's `clientInfo` does not. Read from the
+ * manifest rather than written here: the literal that used to be here said
+ * 0.1 while the package said 0.2, within a day of being written.
+ */
+export const SERVER = { name: 'ahpc', version: version() };
+const METHOD_NOT_FOUND = -32601;
+const INVALID_PARAMS = -32602;
+const INTERNAL = -32603;
+const bag = (value) => (typeof value === 'object' && value !== null && !Array.isArray(value) ? value : {});
+/** The tools, in the shape `tools/list` puts them on the wire. */
+export const listing = (groups = []) => ({
+    tools: served(groups).map((tool) => ({
+        name: tool.name,
+        title: tool.title,
+        description: tool.description,
+        inputSchema: tool.input,
+        annotations: { readOnlyHint: tool.readOnly },
+    })),
+});
+/**
+ * Run one tool and shape the answer the way `tools/call` wants it.
+ *
+ * A tool that throws is *not* a protocol error. MCP has `isError` on the
+ * result for exactly this: the call reached the tool and the tool said no,
+ * which a model can read and act on, where a JSON-RPC error is a transport
+ * fault it can only give up over. So a refusal from the host - a session that
+ * is gone, a directory it does not serve - comes back as content.
+ */
+export async function call(host, name, input, report, groups = []) {
+    const tool = named(name);
+    if (tool === undefined) {
+        return {
+            isError: true,
+            content: [{ type: 'text', text: `No tool called ${name}. Ask tools/list for what there is.` }],
+        };
+    }
+    // Exists, but this server was not started with it. Said as itself rather
+    // than as "no such tool", because the difference is one flag and only the
+    // person who started this can supply it.
+    if (tool.group !== undefined && !groups.includes(tool.group)) {
+        return {
+            isError: true,
+            content: [{ type: 'text', text: `${name} is in the ${tool.group} group, which this server was not started with. It needs --mcp-tools ${tool.group}.` }],
+        };
+    }
+    try {
+        const answer = await tool.run(host, bag(input), report);
+        return {
+            // Both, because clients differ: the text is what a model reads and
+            // `structuredContent` is what a program does, and sending only the
+            // second leaves older clients with an empty result.
+            content: [{ type: 'text', text: JSON.stringify(answer, null, 2) }],
+            structuredContent: bag(answer).constructor === Object && !Array.isArray(answer) && answer !== null
+                ? answer
+                : { result: answer },
+        };
+    }
+    catch (error) {
+        return {
+            isError: true,
+            content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
+        };
+    }
+}
+/**
+ * Somewhere for a running tool to say what it is doing, if anybody asked.
+ *
+ * A caller opts in by putting a `progressToken` in `_meta` on the request, and
+ * `undefined` here means it did not - in which case a tool that reports
+ * anything is writing to nowhere, which is exactly what should happen. The
+ * counter is this closure's, because `progress` MUST increase and a tool
+ * counting for itself would be a tool that has to know about the protocol.
+ */
+function reporter(message, notify) {
+    const token = bag(bag(message.params)._meta).progressToken;
+    if (notify === undefined)
+        return undefined;
+    if (typeof token !== 'string' && typeof token !== 'number')
+        return undefined;
+    let count = 0;
+    return (said) => {
+        count += 1;
+        const params = { progressToken: token, progress: count, message: said };
+        notify({ method: 'notifications/progress', params });
+    };
+}
+/**
+ * Answer one message.
+ *
+ * `undefined` where there is nothing to send back, which is a notification -
+ * and answering one anyway is a protocol error on this end, not a courtesy.
+ */
+export async function answer(host, message, options) {
+    const method = typeof message.method === 'string' ? message.method : '';
+    const id = message.id ?? null;
+    const notification = message.id === undefined;
+    if (method === 'notifications/initialized' || method.startsWith('notifications/'))
+        return undefined;
+    if (notification)
+        return undefined;
+    const ok = (result) => ({ jsonrpc: '2.0', id, result });
+    const no = (code, said) => ({ jsonrpc: '2.0', id, error: { code, message: said } });
+    if (method === 'initialize') {
+        /*
+         * The client's version where this can speak it, and the newest otherwise.
+         *
+         * `lifecycle` says a server answering a version it was not asked for is
+         * telling the client to take that one or disconnect, so answering our
+         * own regardless would refuse every client a release behind for no
+         * reason. A version this cannot speak gets the newest it can, which is
+         * the offer the client then accepts or drops.
+         */
+        const asked = bag(message.params).protocolVersion;
+        return ok({
+            protocolVersion: typeof asked === 'string' && SPOKEN.includes(asked) ? asked : PROTOCOL,
+            capabilities: { tools: { listChanged: false } },
+            serverInfo: { name: options.name, version: options.version },
+        });
+    }
+    if (method === 'ping')
+        return ok({});
+    if (method === 'tools/list')
+        return ok(listing(options.groups));
+    if (method === 'tools/call') {
+        const params = bag(message.params);
+        const name = typeof params.name === 'string' ? params.name : '';
+        if (name === '')
+            return no(INVALID_PARAMS, 'tools/call needs a name.');
+        try {
+            return ok(await call(host, name, params.arguments, reporter(message, options.notify), options.groups));
+        }
+        catch (error) {
+            return no(INTERNAL, error instanceof Error ? error.message : String(error));
+        }
+    }
+    return no(METHOD_NOT_FOUND, `This server does not implement ${method}. It serves tools and nothing else.`);
+}

package/dist/src/mcp/stdio.d.ts

@@ -0,0 +1,14 @@
+import type { HostConnection } from '../ahp/connection.js';
+/**
+ * Serve until stdin closes.
+ *
+ * Sequential rather than concurrent: `send_turn` blocks for as long as a model
+ * takes, and running the next message while it waits would answer out of
+ * order. A client that wants two things at once opens two sessions.
+ */
+export declare function stdio(host: HostConnection, options: {
+    name: string;
+    version: string;
+    groups?: readonly string[];
+    onProblem?(said: string): void;
+}): Promise<void>;

package/dist/src/mcp/stdio.js

@@ -0,0 +1,64 @@
+/*
+ * MCP over the process's own standard streams.
+ *
+ * The transport a client that launched this process uses: one JSON-RPC
+ * message per line on stdin, one per line on stdout, and nothing else on
+ * stdout ever - a stray `console.log` here is a parse error at the other end,
+ * which is why everything this says goes to stderr.
+ */
+import { answer } from './serve.js';
+/**
+ * Serve until stdin closes.
+ *
+ * Sequential rather than concurrent: `send_turn` blocks for as long as a model
+ * takes, and running the next message while it waits would answer out of
+ * order. A client that wants two things at once opens two sessions.
+ */
+export async function stdio(host, options) {
+    const say = (value) => { process.stdout.write(`${JSON.stringify(value)}\n`); };
+    let rest = '';
+    await new Promise((done) => {
+        let running = Promise.resolve();
+        const take = (line) => {
+            const said = line.trim();
+            if (said === '')
+                return;
+            running = running.then(async () => {
+                let message;
+                try {
+                    message = JSON.parse(said);
+                }
+                catch {
+                    // No id to answer against, so there is nobody to tell. Said on
+                    // stderr, where a person debugging their client will find it.
+                    options.onProblem?.(`Not JSON: ${said.slice(0, 200)}`);
+                    return;
+                }
+                const reply = await answer(host, message, {
+                    ...options,
+                    // A notification mid-request is free here: stdout is a stream and
+                    // the client is already reading lines off it. The HTTP half has to
+                    // choose a response type before it can say anything at all.
+                    notify: (notification) => say({ jsonrpc: '2.0', ...notification }),
+                });
+                if (reply !== undefined)
+                    say(reply);
+            }).catch((error) => {
+                options.onProblem?.(error instanceof Error ? error.message : String(error));
+            });
+        };
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            rest += chunk;
+            for (;;) {
+                const at = rest.indexOf('\n');
+                if (at === -1)
+                    break;
+                take(rest.slice(0, at));
+                rest = rest.slice(at + 1);
+            }
+        });
+        process.stdin.on('end', () => { take(rest); rest = ''; void running.then(() => done()); });
+        process.stdin.on('close', () => { void running.then(() => done()); });
+    });
+}