@softov/ahpc 0.2.0 → 0.4.0

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

@@ -1,17 +1,26 @@
 import type { HostConnection } from '../ahp/connection.js';
-/** The version of MCP this speaks, and the one it answers `initialize` with. */
+/** 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, so this is the
- * only version string in the source. Cosmetic - a client displays it and
- * nothing branches on it - and deliberately not read out of `package.json`,
- * which sits at a different depth in the published tree than it does here.
+ * 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: {
-    readonly name: "ahpc";
-    readonly version: "0.1";
+    name: string;
+    version: string;
 };
 /** A JSON-RPC request or notification, as far as this needs to read one. */
 export interface Incoming {
@@ -20,6 +29,21 @@ export interface Incoming {
     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';
@@ -35,7 +59,7 @@ export type Outgoing = {
     result?: never;
 });
 /** The tools, in the shape `tools/list` puts them on the wire. */
-export declare const listing: () => unknown;
+export declare const listing: (groups?: readonly string[]) => unknown;
 /**
  * Run one tool and shape the answer the way `tools/call` wants it.
  *
@@ -45,7 +69,7 @@ export declare const listing: () => unknown;
  * 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): Promise<unknown>;
+export declare function call(host: HostConnection, name: string, input: unknown, report?: Report, groups?: readonly string[]): Promise<unknown>;
 /**
  * Answer one message.
  *
@@ -55,4 +79,18 @@ export declare function call(host: HostConnection, name: string, input: unknown)
 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

@@ -13,25 +13,35 @@
  * obliged to answer them, and a caller that asks is told the method is not
  * there, which is the truth.
  */
-import { TOOLS, named } from './tools.js';
-/** The version of MCP this speaks, and the one it answers `initialize` with. */
+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, so this is the
- * only version string in the source. Cosmetic - a client displays it and
- * nothing branches on it - and deliberately not read out of `package.json`,
- * which sits at a different depth in the published tree than it does here.
+ * 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: '0.1' };
+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 = () => ({
-    tools: TOOLS.map((tool) => ({
+export const listing = (groups = []) => ({
+    tools: served(groups).map((tool) => ({
         name: tool.name,
         title: tool.title,
         description: tool.description,
@@ -48,7 +58,7 @@ export const listing = () => ({
  * 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) {
+export async function call(host, name, input, report, groups = []) {
     const tool = named(name);
     if (tool === undefined) {
         return {
@@ -56,8 +66,17 @@ export async function call(host, name, input) {
             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));
+        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
@@ -75,6 +94,28 @@ export async function call(host, name, input) {
         };
     }
 }
+/**
+ * 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.
  *
@@ -92,8 +133,18 @@ export async function answer(host, message, options) {
     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: PROTOCOL,
+            protocolVersion: typeof asked === 'string' && SPOKEN.includes(asked) ? asked : PROTOCOL,
             capabilities: { tools: { listChanged: false } },
             serverInfo: { name: options.name, version: options.version },
         });
@@ -101,14 +152,14 @@ export async function answer(host, message, options) {
     if (method === 'ping')
         return ok({});
     if (method === 'tools/list')
-        return ok(listing());
+        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));
+            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));

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

@@ -9,5 +9,6 @@ import type { HostConnection } from '../ahp/connection.js';
 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

@@ -34,7 +34,13 @@ export async function stdio(host, options) {
                     options.onProblem?.(`Not JSON: ${said.slice(0, 200)}`);
                     return;
                 }
-                const reply = await answer(host, message, options);
+                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) => {

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

@@ -15,10 +15,28 @@ export interface Schema {
     required?: string[];
     additionalProperties?: boolean;
 }
+/**
+ * A set of tools a caller has to ask for by name.
+ *
+ * The core table - sessions, turns, attention - is what a server is for and is
+ * always served. These are not: a tool table is read by a model alongside
+ * everything else it was given, and thirty tools is a worse server than twelve
+ * for the thing almost everybody wants. So they are opt-*in*, one group at a
+ * time, and a caller that needs files says so.
+ */
+export type Group = 'resources' | 'terminals' | 'automations' | 'changes';
+/** Every group there is, for `--mcp-tools` to name in its help. */
+export declare const GROUPS: readonly Group[];
 /** One tool, as MCP describes it and as this client runs it. */
 export interface Tool {
     /** The name a caller uses. MCP has no dots, so these are underscored. */
     name: string;
+    /**
+     * The group that has to be turned on for this to be served.
+     *
+     * Absent is core: always there, never asked for.
+     */
+    group?: Group;
     /** A short label, for a client that shows one. */
     title: string;
     /** What it does and when to reach for it, written for a model. */
@@ -26,8 +44,25 @@ export interface Tool {
     input: Schema;
     /** Whether it changes anything, which some clients ask a person about. */
     readOnly: boolean;
-    run(host: HostConnection, input: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Do it.
+     *
+     * `report` is where to say what is happening while a long one runs, and is
+     * absent unless the caller asked for progress and the transport can carry
+     * it. A tool that reports nothing is a tool that finishes quickly enough
+     * not to need to.
+     */
+    run(host: HostConnection, input: Record<string, unknown>, report?: (said: string) => void): Promise<unknown>;
 }
 export declare const TOOLS: Tool[];
-/** One tool by the name a caller used, or nothing. */
+/**
+ * One tool by the name a caller used, or nothing.
+ *
+ * Over the whole table, including groups nobody turned on - whether a tool
+ * exists and whether this server serves it are different questions, and
+ * `served` answers the second. Telling somebody the tool is in a group they
+ * did not ask for is a better answer than telling them it does not exist.
+ */
 export declare const named: (name: string) => Tool | undefined;
+/** The tools a server started with these groups serves. */
+export declare const served: (groups?: readonly string[]) => Tool[];