@hardfin/cli 0.0.2-dev.10 → 0.0.2-dev.11

package/README.md

@@ -185,6 +185,42 @@ environment, so `hardfin login` works out of the box.
 | `clientId`, or `HARDFIN_CLIENT_ID` | the client this CLI names itself as | the seeded Hardfin CLI client |
 | `issuerUrl`, or `HARDFIN_ISSUER_URL` | the authorization server | the API's host root |
 
+## Serving an agent
+
+```sh
+hardfin mcp
+```
+
+It speaks the Model Context Protocol on standard input and output, so Claude, Codex or any
+other client can run Hardfin commands.
+
+```sh
+claude mcp add hardfin -- hardfin mcp
+```
+
+### One tool, and resources for the rest
+
+Every tool a server lists sits in the agent's context for the entire session, so this server
+offers one.
+
+| Offered as | Holds | Costs context |
+| --- | --- | --- |
+| The `hardfin` tool | A list of arguments, such as `["asset", "list", "--limit", "5"]` | Always, and it is about 400 bytes |
+| `hardfin://guide` | Every command, its flags, and the exit codes | Only when the agent reads it |
+| `hardfin://commands` | The command tree as JSON | Only when the agent reads it |
+
+Fifty tools would describe the same surface and crowd out the work. An agent that needs the
+list reads a resource, or runs `["--help"]`.
+
+A tool call runs the CLI itself, so an agent and a person get identical parsing, output and
+exit codes.
+
+### What it signs in as
+
+The server uses whatever credential this machine holds, so an agent acts as the person who
+ran `hardfin login`. Give an agent an API key through `HARDFIN_API_KEY` when it should act
+as an integration instead.
+
 ## Diagnosing a problem
 
 `hardfin status` prints everything a support request needs, and is the first thing to send.

package/dist/cli.js

@@ -5,9 +5,10 @@ import { z } from "zod";
 import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { arch, cpus, homedir, release, totalmem, type, version } from "node:os";
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { createServer } from "node:http";
 import { createHash, randomBytes } from "node:crypto";
+import { createInterface } from "node:readline";
 //#region src/command/registry.ts
 /** ExitCode is what the process returns, and what an agent branches on. */
 const ExitCode = {
@@ -1310,6 +1311,190 @@ async function runLogout(input) {
 	return ExitCode.OK;
 }
 //#endregion
+//#region src/mcp/server.ts
+const PROTOCOL_VERSION = "2025-06-18";
+const GUIDE_URI = "hardfin://guide";
+const COMMANDS_URI = "hardfin://commands";
+/**
+* One tool, because every tool a server lists sits in the agent's context for the whole
+* session. The commands themselves are resources, which cost nothing until one is read.
+*/
+const TOOL = {
+	name: "hardfin",
+	description: "Run a Hardfin CLI command against the Hardfin API. Pass the arguments as a list, such as [\"asset\", \"list\", \"--limit\", \"5\"]. Run [\"--help\"] for the commands, or read the hardfin://guide resource.",
+	inputSchema: {
+		type: "object",
+		properties: { args: {
+			type: "array",
+			items: { type: "string" },
+			description: "The arguments to hardfin, without the program name"
+		} },
+		required: ["args"]
+	}
+};
+/** toResponse answers one request, and answers nothing to a notification. */
+async function toResponse(request, commands, run) {
+	const answer = (result) => ({
+		jsonrpc: "2.0",
+		id: request.id ?? null,
+		result
+	});
+	switch (request.method) {
+		case "initialize": return answer({
+			protocolVersion: toProtocolVersion(request.params),
+			capabilities: {
+				tools: {},
+				resources: {}
+			},
+			serverInfo: {
+				name: "hardfin",
+				version: version$1
+			}
+		});
+		case "tools/list": return answer({ tools: [TOOL] });
+		case "resources/list": return answer({ resources: [{
+			uri: GUIDE_URI,
+			name: "Hardfin CLI guide",
+			description: "Every command, its flags, and the exit codes",
+			mimeType: "text/markdown"
+		}, {
+			uri: COMMANDS_URI,
+			name: "Hardfin CLI commands",
+			description: "The command tree as JSON",
+			mimeType: "application/json"
+		}] });
+		case "resources/read": return answer(toResource(String(request.params?.["uri"] ?? ""), commands));
+		case "tools/call": return answer(await toToolResult(request.params, run));
+		case "ping": return answer({});
+		default:
+			if (request.id === void 0 || request.id === null) return;
+			return {
+				jsonrpc: "2.0",
+				id: request.id,
+				error: {
+					code: -32601,
+					message: `${request.method} is not a method this server offers`
+				}
+			};
+	}
+}
+function toProtocolVersion(params) {
+	const asked = params?.["protocolVersion"];
+	return typeof asked === "string" ? asked : PROTOCOL_VERSION;
+}
+function toResource(uri, commands) {
+	if (uri === GUIDE_URI) return { contents: [{
+		uri,
+		mimeType: "text/markdown",
+		text: toGuide(commands, version$1)
+	}] };
+	if (uri === COMMANDS_URI) return { contents: [{
+		uri,
+		mimeType: "application/json",
+		text: JSON.stringify(toTree(commands), null, 2)
+	}] };
+	return {
+		contents: [],
+		isError: true
+	};
+}
+/** toTree names every command and what it takes, without the schemas a tool list would carry. */
+function toTree(commands) {
+	return commands.map((command) => ({
+		name: command.name,
+		summary: command.summary,
+		arguments: command.arguments.map((argument) => argument.name),
+		flags: command.flags.map((flag) => flag.valueName ? `--${flag.name} <${flag.valueName}>` : `--${flag.name}`),
+		subcommands: command.subcommands ? toTree(command.subcommands) : void 0
+	}));
+}
+async function toToolResult(params, run) {
+	const args = (params?.["arguments"])?.args;
+	if (!Array.isArray(args) || args.some((entry) => typeof entry !== "string")) return {
+		content: [{
+			type: "text",
+			text: "args must be a list of strings, such as [\"asset\", \"list\"]"
+		}],
+		isError: true
+	};
+	const outcome = await run(args);
+	return {
+		content: [{
+			type: "text",
+			text: [outcome.stdout, outcome.stderr].filter((part) => part.trim() !== "").join("\n") || `hardfin exited ${outcome.code}`
+		}],
+		isError: outcome.code !== 0
+	};
+}
+/** toCliRunner runs the CLI itself, so a tool call parses exactly as a terminal would. */
+function toCliRunner() {
+	return (args) => new Promise((resolve) => {
+		const child = spawn(process.execPath, [process.argv[1] ?? "", ...args], { env: {
+			...process.env,
+			HARDFIN_NO_BROWSER: "1"
+		} });
+		let stdout = "";
+		let stderr = "";
+		child.stdout.on("data", (chunk) => {
+			stdout += chunk.toString();
+		});
+		child.stderr.on("data", (chunk) => {
+			stderr += chunk.toString();
+		});
+		child.on("close", (code) => resolve({
+			stdout,
+			stderr,
+			code: code ?? 1
+		}));
+	});
+}
+/** serve answers requests on stdin until the client closes it. */
+async function serve(commands, run = toCliRunner()) {
+	const lines = createInterface({ input: process.stdin });
+	for await (const line of lines) {
+		if (line.trim() === "") continue;
+		let response;
+		try {
+			response = await toResponse(JSON.parse(line), commands, run);
+		} catch (error) {
+			response = {
+				jsonrpc: "2.0",
+				id: null,
+				error: {
+					code: -32700,
+					message: error instanceof Error ? error.message : String(error)
+				}
+			};
+		}
+		if (response) process.stdout.write(`${JSON.stringify(response)}\n`);
+	}
+}
+//#endregion
+//#region src/command/mcp.ts
+const mcpCommand = defineCommand({
+	name: "mcp",
+	summary: "Serve this CLI to an agent over the Model Context Protocol",
+	description: "Speaks the Model Context Protocol on standard input and output. It offers one tool, because every tool an agent is told about occupies its context for the whole session, and serves the commands as resources the agent reads only when it needs them.",
+	arguments: [],
+	flags: [{
+		name: "json",
+		description: "Accepted for consistency, and ignored, because the protocol decides the output",
+		schema: z.boolean()
+	}],
+	examples: [{
+		description: "Register with an agent",
+		command: "hardfin mcp"
+	}, {
+		description: "Add it to Claude Code",
+		command: "claude mcp add hardfin -- hardfin mcp"
+	}],
+	run: runMcp
+});
+async function runMcp(input) {
+	await serve(input.commands);
+	return ExitCode.OK;
+}
+//#endregion
 //#region src/command/operation.ts
 const INPUT_FLAG = {
 	name: "input",
@@ -2898,7 +3083,8 @@ const commands = [
 	...surfaceCommands,
 	apiCommand,
 	configCommand,
-	agentGuideCommand
+	agentGuideCommand,
+	mcpCommand
 ];
 //#endregion
 //#region src/command/validate.ts

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hardfin/cli",
-    "version": "0.0.2-dev.10",
+    "version": "0.0.2-dev.11",
     "description": "Command line interface for the Hardfin API",
     "license": "Apache-2.0",
     "author": "Hardfin, Inc.",