@xalia/agent 1.0.19

package/src/mcpServerManager.ts

@@ -0,0 +1,365 @@
+import { ChatCompletionTool } from "openai/resources.mjs";
+import {
+  SSEClientTransport,
+  SSEClientTransportOptions,
+} from "@modelcontextprotocol/sdk/client/sse.js";
+import { Client as McpClient } from "@modelcontextprotocol/sdk/client/index.js";
+import { TokenAuth } from "./tokenAuth";
+import { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { strict as assert } from "assert";
+import { getLogger } from "@xalia/xmcp/sdk";
+
+const logger = getLogger();
+
+/// Callback into an Mcp server
+export type McpCallback = { (args: string): Promise<string> };
+
+/// Map of tool name to callback
+export type McpCallbacks = { [toolName: string]: McpCallback };
+
+/// Map of tool name to enabled flag
+export type EnabledTools = { [toolName: string]: boolean };
+
+/// This represents the full configuration of McpServers and tools.  It cannot
+/// be used directly by this class (since this class does not currently handle
+/// creating the transports), but should be usable by a catalogue
+/// (e.g. SudoMcpServerManager) to reconstruct the state.
+export type McpServerManagerSettings = {
+  [serverName: string]: EnabledTools;
+};
+
+/**
+ * The (read-only) McpServerInfo to expose to external classes.  Callers
+ * should not modify this data directly.  Only through the McpServerManager
+ * class.
+ */
+export class McpServerInfo {
+  private readonly tools: Tool[]; // TODO: May not need both tools and toolsMap
+  private readonly toolsMap: { [toolName: string]: Tool };
+  protected enabledToolsMap: EnabledTools;
+
+  constructor(tools: Tool[]) {
+    const toolsMap: { [toolName: string]: Tool } = {};
+
+    for (const mcpTool of tools) {
+      const toolName = mcpTool.name;
+      toolsMap[toolName] = mcpTool;
+    }
+
+    this.tools = tools;
+    this.toolsMap = toolsMap;
+    this.enabledToolsMap = {};
+  }
+
+  public getEnabledTools(): EnabledTools {
+    return this.enabledToolsMap;
+  }
+
+  public getTools(): Tool[] {
+    return this.tools;
+  }
+
+  public getTool(toolName: string): Tool {
+    return this.toolsMap[toolName];
+  }
+}
+
+/**
+ * The internal class holds server info and allows it to be updated. Managed
+ * by McpServerManager.  Do not access these methods except via the
+ * McpServerManager.
+ */
+class McpServerInfoInternal extends McpServerInfo {
+  private readonly client: McpClient;
+  private readonly callbacks: McpCallbacks;
+
+  constructor(client: McpClient, tools: Tool[]) {
+    super(tools);
+
+    const callbacks: McpCallbacks = {};
+
+    for (const mcpTool of tools) {
+      const toolName = mcpTool.name;
+
+      // Create callback
+      const callback = async (argStr: string): Promise<string> => {
+        logger.debug(
+          `cb for ${toolName} invoked with args (${typeof argStr}): ` +
+            `${JSON.stringify(argStr)}`
+        );
+
+        const argsObj = JSON.parse(argStr);
+        const toolResult = await client.callTool({
+          name: toolName,
+          arguments: argsObj,
+        });
+        logger.debug(
+          `cb for ${toolName} returned: ${JSON.stringify(toolResult)}`
+        );
+
+        assert(typeof toolResult === "object");
+        const content = toolResult.content as { [a: number]: unknown };
+        assert(typeof content === "object");
+        assert(content);
+        const content0 = content[0] as { text: string };
+        assert(typeof content0 === "object");
+        const content0Text = content0.text;
+        assert(typeof content0Text === "string");
+        return content0Text;
+      };
+
+      callbacks[toolName] = callback;
+    }
+
+    this.client = client;
+    this.callbacks = callbacks;
+  }
+
+  public async shutdown(): Promise<void> {
+    await this.client.close();
+  }
+
+  public enableTool(toolName: string) {
+    this.enabledToolsMap[toolName] = true;
+  }
+
+  public disableTool(toolName: string) {
+    delete this.enabledToolsMap[toolName];
+  }
+
+  public getCallback(toolName: string) {
+    return this.callbacks[toolName];
+  }
+}
+
+/**
+ * Manage a set of MCP servers, where the tools for each server have an
+ * 'enabled' flag.  Tools are disabled by default.  The set of enabled tools
+ * over all servers is exposed as a single list of OpenAI functions.
+ */
+export class McpServerManager {
+  private mcpServers: { [serverName: string]: McpServerInfoInternal } = {};
+  private enabledToolsDirty: boolean = true;
+  private enabledOpenAITools: ChatCompletionTool[] = [];
+
+  public async shutdown() {
+    await Promise.all(
+      Object.keys(this.mcpServers).map((name) => {
+        logger.debug(`shutting down: ${name}...`);
+        this.mcpServers[name].shutdown();
+      })
+    );
+
+    this.mcpServers = {};
+  }
+
+  public getMcpServerNames(): string[] {
+    return Object.keys(this.mcpServers);
+  }
+
+  public getMcpServer(mcpServerName: string): McpServerInfo {
+    return this.getMcpServerInternal(mcpServerName);
+  }
+
+  public async addMcpServer(
+    mcpServerName: string,
+    url: string,
+    apiKey?: string,
+    tools?: Tool[]
+  ): Promise<void> {
+    logger.debug(`Adding mcp server ${mcpServerName}: ${url}`);
+    const sseTransportOptions: SSEClientTransportOptions = {};
+    if (apiKey) {
+      sseTransportOptions.authProvider = new TokenAuth(apiKey);
+    }
+    const urlO = new URL(url);
+    const transport = new SSEClientTransport(urlO, sseTransportOptions);
+    const client = new McpClient({
+      name: "@xalia/agent",
+      version: "1.0.0",
+    });
+
+    try {
+      await client.connect(transport);
+    } catch (e) {
+      // TODO: is this catch necessary?
+      await client.close();
+      throw e;
+    }
+    await this.addMcpServerWithClient(client, mcpServerName, tools);
+  }
+
+  /**
+   * Add MCP server from an already connected McpClient.
+   */
+  public async addMcpServerWithClient(
+    client: McpClient,
+    mcpServerName: string,
+    tools?: Tool[]
+  ): Promise<void> {
+    try {
+      // TODO; require the tools to be passed in.
+
+      if (!tools) {
+        const mcpTools = await client.listTools();
+        tools = mcpTools.tools;
+      }
+
+      this.mcpServers[mcpServerName] = new McpServerInfoInternal(client, tools);
+    } catch (e) {
+      await client.close();
+      throw e;
+    }
+  }
+
+  public async removeMcpServer(mcpServerName: string) {
+    const server = this.getMcpServerInternal(mcpServerName);
+    delete this.mcpServers[mcpServerName];
+    await server.shutdown();
+    this.enabledToolsDirty = true;
+  }
+
+  public enableAllTools(mcpServerName: string) {
+    logger.debug(`enableAllTools: ${mcpServerName}`);
+    const server = this.getMcpServerInternal(mcpServerName);
+    for (const tool of server.getTools()) {
+      logger.debug(`enable: ${tool.name}`);
+      server.enableTool(tool.name);
+    }
+    this.enabledToolsDirty = true;
+  }
+
+  public disableAllTools(mcpServerName: string) {
+    logger.debug(`disableAllTools: ${mcpServerName}`);
+    const server = this.getMcpServerInternal(mcpServerName);
+    for (const tool of server.getTools()) {
+      logger.debug(`disable: ${tool.name}`);
+      server.disableTool(tool.name);
+    }
+    this.enabledToolsDirty = true;
+  }
+
+  public enableTool(mcpServerName: string, toolName: string) {
+    logger.debug(`enableTool: ${mcpServerName} ${toolName}`);
+    const server = this.getMcpServerInternal(mcpServerName);
+    server.enableTool(toolName);
+    this.enabledToolsDirty = true;
+  }
+
+  public disableTool(mcpServerName: string, toolName: string) {
+    const server = this.getMcpServerInternal(mcpServerName);
+    server.disableTool(toolName);
+    this.enabledToolsDirty = true;
+  }
+
+  public getOpenAITools(): ChatCompletionTool[] {
+    if (this.enabledToolsDirty) {
+      this.enabledOpenAITools = computeOpenAIToolList(this.mcpServers);
+      this.enabledToolsDirty = false;
+    }
+
+    return this.enabledOpenAITools;
+  }
+
+  /**
+   * Note the `qualifiedToolName` is the full `{mcpServerName}/{toolName}` as
+   * in the openai spec.
+   */
+  public async invoke(
+    qualifiedToolName: string,
+    args: unknown
+  ): Promise<string> {
+    const [mcpServerName, toolName] = splitQualifiedName(qualifiedToolName);
+    logger.debug(`invoke: qualified: ${qualifiedToolName}`);
+    logger.debug(
+      `invoke: mcpServerName: ${mcpServerName}, toolName: ${toolName}`
+    );
+    logger.debug(`invoke: args: ${JSON.stringify(args)}`);
+
+    const server = this.getMcpServerInternal(mcpServerName);
+    const cb = server.getCallback(toolName);
+    if (!cb) {
+      throw `Unknown tool ${qualifiedToolName}`;
+    }
+
+    return cb(JSON.stringify(args));
+  }
+
+  /**
+   * "Settings" refers to the set of added servers and enabled tools.
+   */
+  public getMcpServerSettings(): McpServerManagerSettings {
+    const config: McpServerManagerSettings = {};
+    for (const [serverName, server] of Object.entries(this.mcpServers)) {
+      config[serverName] = structuredClone(server.getEnabledTools());
+    }
+
+    return config;
+  }
+
+  private getMcpServerInternal(mcpServerName: string): McpServerInfoInternal {
+    const server = this.mcpServers[mcpServerName];
+    if (server) {
+      return server;
+    }
+    throw Error(`unknown server ${mcpServerName}`);
+  }
+}
+
+export function computeQualifiedName(
+  mcpServerName: string,
+  toolName: string
+): string {
+  return `${mcpServerName}__${toolName}`;
+}
+
+export function splitQualifiedName(
+  qualifiedToolName: string
+): [string, string] {
+  const delimIdx = qualifiedToolName.indexOf("__");
+  if (delimIdx < 0) {
+    throw Error(`invalid qualified name: ${qualifiedToolName}`);
+  }
+
+  return [
+    qualifiedToolName.slice(0, delimIdx),
+    qualifiedToolName.slice(delimIdx + 2),
+  ];
+}
+
+export function computeOpenAIToolList(mcpServers: {
+  [mcpServer: string]: McpServerInfoInternal;
+}): ChatCompletionTool[] {
+  const openaiTools: ChatCompletionTool[] = [];
+
+  for (const mcpServerName in mcpServers) {
+    const mcpServer = mcpServers[mcpServerName];
+    const tools = mcpServer.getTools();
+    const enabled = mcpServer.getEnabledTools();
+
+    for (const mcpTool of tools) {
+      const toolName = mcpTool.name;
+      if (enabled[toolName]) {
+        const qualifiedName = computeQualifiedName(mcpServerName, toolName);
+        const openaiTool = mcpToolToOpenAITool(mcpTool, qualifiedName);
+        openaiTools.push(openaiTool);
+      }
+    }
+  }
+
+  return openaiTools;
+}
+
+export function mcpToolToOpenAITool(
+  tool: Tool,
+  qualifiedName?: string
+): ChatCompletionTool {
+  return {
+    type: "function",
+    function: {
+      name: qualifiedName || tool.name,
+      description: tool.description,
+      parameters: tool.inputSchema,
+    },
+  };
+}

package/src/nodePlatform.ts

@@ -0,0 +1,24 @@
+import * as fs from "fs";
+import { execSync } from "child_process";
+import { IPlatform } from "./iplatform";
+
+/**
+ * Implementation of the IPlatform interface for node.js
+ */
+export const NODE_PLATFORM: IPlatform = {
+  openUrl: (url: string) => {
+    const platform = process.platform;
+    if (platform === "darwin") {
+      execSync(`open '${url}'`);
+    } else if (platform === "linux") {
+      execSync(`xdg-open '${url}'`);
+    } else if (platform === "win32") {
+      execSync(`start '${url}'`);
+    } else {
+      throw `Unknown platform ${platform}`;
+    }
+  },
+  load: async (filename: string): Promise<string> => {
+    return fs.readFileSync(filename, { encoding: "utf8" });
+  },
+};

package/src/openAILLM.ts

@@ -0,0 +1,43 @@
+import { ILLM } from "./llm";
+import { OpenAI } from "openai";
+
+export class OpenAILLM implements ILLM {
+  private readonly openai: OpenAI;
+  private model: string;
+
+  constructor(
+    apiKey: string,
+    apiUrl: string | undefined,
+    model: string | undefined
+  ) {
+    this.openai = new OpenAI({
+      apiKey,
+      baseURL: apiUrl,
+      dangerouslyAllowBrowser: true,
+    });
+    this.model = model || "gpt-4o-mini";
+  }
+
+  public setModel(model: string) {
+    this.model = model;
+  }
+
+  getModel(): string {
+    return this.model;
+  }
+
+  getUrl(): string {
+    return this.openai.baseURL;
+  }
+
+  public async getConversationResponse(
+    messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[],
+    tools?: OpenAI.Chat.Completions.ChatCompletionTool[]
+  ): Promise<OpenAI.Chat.Completions.ChatCompletion> {
+    return this.openai.chat.completions.create({
+      model: this.model,
+      messages,
+      tools,
+    });
+  }
+}

package/src/options.ts

@@ -0,0 +1,103 @@
+import { boolean, option, optional, string, flag, number } from "cmd-ts";
+import { ArgParser } from "cmd-ts/dist/cjs/argparser";
+import { Descriptive, ProvidesHelp } from "cmd-ts/dist/cjs/helpdoc";
+
+export type Option = ReturnType<typeof option>;
+export type OptionalOption = ArgParser<string | undefined> &
+  ProvidesHelp &
+  Partial<Descriptive>;
+
+/// Prevents env content from being displayed in the help text.
+export function secretOption({
+  long,
+  short,
+  env,
+  description,
+}: {
+  long: string;
+  short?: string;
+  env?: string;
+  description: string;
+}): OptionalOption {
+  if (env) {
+    return option({
+      type: optional(string),
+      long,
+      short,
+      description: `${description} [env: ${env}]`,
+      defaultValue: () => process.env[env],
+      defaultValueIsSerializable: false, // hides the value from --help
+    });
+  }
+
+  return option({
+    type: optional(string),
+    long,
+    short,
+    description: `${description} (can also be set via ${env} env var)`,
+  });
+}
+
+export const promptFile = option({
+  type: optional(string),
+  long: "prompt",
+  short: "p",
+  description: "File containing user's first prompt to LLM",
+});
+
+export const imageFile = option({
+  type: optional(string),
+  long: "image",
+  short: "i",
+  description: "File containing image input",
+});
+
+export const systemPromptFile = option({
+  type: optional(string),
+  long: "sysprompt",
+  short: "s",
+  description: "File containing system prompt",
+});
+
+export const llmModel = option({
+  type: optional(string),
+  long: "model",
+  short: "m",
+  description: "LLM model",
+  env: "LLM_MODEL",
+});
+
+export const oneShot = flag({
+  type: boolean,
+  long: "one-shot",
+  short: "1",
+  description: "Exit after first reply (implies --approve-tools)",
+});
+
+export const approveTools = flag({
+  type: boolean,
+  long: "approve-tools",
+  short: "y",
+  description: "Automatically approve all tool calls",
+});
+
+export const approveToolsUpTo = option({
+  type: optional(number),
+  long: "approve-tools-up-to",
+  description: "Automatically approve all tool calls up to some number",
+});
+
+export const openaiApiKey = secretOption({
+  long: "openai-api-key",
+  short: "o",
+  description: "OpenAI (or compatible protocol) API Key",
+  env: "OPENAI_API_KEY",
+});
+
+export const openaiApiUrl = option({
+  type: optional(string),
+  long: "openai-api-url",
+  short: "u",
+  description: "OpenAI (or compatible protocol) RPC endpoint url",
+  env: "OPENAI_API_URL",
+});

package/src/prompt.ts

@@ -0,0 +1,93 @@
+import readline from "readline";
+
+const DEFAULT_PROMPT: string = "USER: ";
+
+export class Prompt {
+  private line: string | undefined;
+  private online: { (line: string | undefined): void } | undefined;
+  // private onerror: { (reason?: any): void } | undefined;
+  private prompt: readline.Interface;
+
+  constructor() {
+    this.prompt = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      prompt: DEFAULT_PROMPT,
+    });
+
+    this.prompt.on("line", (line) => {
+      this.line = line;
+      this.resolve();
+    });
+    this.prompt.on("close", () => {
+      this.line = undefined;
+      this.resolve();
+    });
+  }
+
+  async run(prompt?: string): Promise<string | undefined> {
+    // Clear any line
+    this.line = "";
+
+    return new Promise<string | undefined>((r) => {
+      this.online = r;
+      if (prompt) {
+        this.prompt.setPrompt(prompt);
+      }
+      this.prompt.prompt();
+      if (prompt) {
+        this.prompt.setPrompt(DEFAULT_PROMPT);
+      }
+    });
+  }
+
+  shutdown(): void {
+    this.prompt.close();
+  }
+
+  private resolve(): void {
+    if (this.online) {
+      this.online(this.line);
+    }
+    this.online = undefined;
+  }
+}
+
+/**
+ * Support prompts:
+ *  - some text                (msg: some text, cmds: undefined)
+ *  - :i image.png some text   (msg: some text, cmds: ["i", "image.png"])
+ *  - :i image.png             (msg: undefined, cmds: ["i", "image.png"])
+ *  - :l                       (msg: undefined, cmds: ["l"])
+ *  - :e toolName ..           (msg: undefined, cmds: ["e", "toolName", ...])
+ *  - :ea toolName ..          (msg: undefined, cmds: ["ea", "toolName", ...])
+ */
+export function parsePrompt(prompt: string): {
+  msg?: string;
+  cmds?: string[];
+} {
+  prompt = prompt.trim();
+
+  let msg: string | undefined = undefined;
+  let cmds: string[] | undefined = undefined;
+
+  if (prompt.startsWith(":") || prompt.startsWith("/")) {
+    cmds = prompt.split(" ");
+    cmds[0] = cmds[0].slice(1);
+
+    if (cmds[0] == "i") {
+      // :i is special as it may have a trailing message
+      const fileDelim = prompt.indexOf(" ", 3);
+      if (fileDelim < 0) {
+        cmds = [cmds[0], prompt.slice(3)];
+      } else {
+        msg = prompt.slice(fileDelim + 1);
+        cmds = [cmds[0], prompt.slice(3, fileDelim)];
+      }
+    }
+  } else {
+    msg = prompt;
+  }
+
+  return { msg, cmds };
+}