@isolo/trinity 1.0.2

package/src/Config.ts

@@ -0,0 +1,89 @@
+import path from "node:path";
+
+export class Config {
+  private static instance: Config | null = null;
+
+  private _mode: "stdio" | "http" = "stdio";
+  private _targetFolder: string = "";
+  private _glob: string = "**/*.ts";
+  private _logFile: string = "";
+  private _port: number = 3000;
+
+  private constructor() {}
+
+  static getInstance(): Config {
+    if (!Config.instance) {
+      Config.instance = new Config();
+    }
+    return Config.instance;
+  }
+
+  parse(argv: string[]): void {
+    // Parse CLI arguments
+    for (let i = 0; i < argv.length; i++) {
+      switch (argv[i]) {
+        case "--target":
+          this._targetFolder = argv[++i];
+          break;
+        case "--glob":
+          this._glob = argv[++i];
+          break;
+        case "--port":
+          this._port = parseInt(argv[++i], 10);
+          break;
+      }
+    }
+
+    // Env fallbacks (CLI takes priority)
+    const envMode = process.env.MCP_MODE;
+    if (envMode === "http" || envMode === "stdio") {
+      this._mode = envMode;
+    }
+
+    if (!this._glob || this._glob === "**/*.ts") {
+      this._glob = process.env.MCP_GLOB || "**/*.ts";
+    }
+
+    if (process.env.LOG_FILE) {
+      this._logFile = process.env.LOG_FILE;
+    }
+
+    if (!this._targetFolder) {
+      throw new Error(
+        "Missing required argument: --target <path>. Specify the folder containing tool files."
+      );
+    }
+
+    // Resolve to absolute path
+    this._targetFolder = path.resolve(this._targetFolder);
+
+    // Default log file relative to target folder
+    if (!this._logFile) {
+      this._logFile = path.join(this._targetFolder, "debug.log");
+    }
+  }
+
+  get mode(): "stdio" | "http" {
+    return this._mode;
+  }
+
+  get targetFolder(): string {
+    return this._targetFolder;
+  }
+
+  get glob(): string {
+    return this._glob;
+  }
+
+  get logFile(): string {
+    return this._logFile;
+  }
+
+  get logDest(): "stdout" | "file" {
+    return this._mode === "http" ? "stdout" : "file";
+  }
+
+  get port(): number {
+    return this._port;
+  }
+}

package/src/Logger.ts

@@ -0,0 +1,52 @@
+import fs from "node:fs";
+import { Config } from "./Config.js";
+import safeJsonStringify from "json-stringify-safe";
+
+type LogLevel = "INFO" | "WARN" | "ERROR" | "DEBUG";
+
+export class Logger {
+  private name: string;
+  private config: Config;
+
+  constructor(requester: string | { name: string }) {
+    this.name = typeof requester === "string" ? requester : requester.name;
+    this.config = Config.getInstance();
+  }
+
+  debug(msg: string, meta?: any): void {
+    this.log("DEBUG", msg, meta);
+  }
+
+  info(msg: string, meta?: any): void {
+    this.log("INFO", msg, meta);
+  }
+
+  warn(msg: string, meta?: any): void {
+    this.log("WARN", msg, meta);
+  }
+
+  error(msg: string, meta?: any): void {
+    this.log("ERROR", msg, meta);
+  }
+
+  private format(level: LogLevel, msg: string, meta: any = {}): string {
+    const timestamp = new Date().toISOString();
+    const logEntry = {
+      timestamp,
+      level,
+      name: this.name,
+      msg,
+      ...(Object.keys(meta).length > 0 && { meta }),
+    };
+    return safeJsonStringify(logEntry);
+  }
+
+  private log(level: LogLevel, msg: string, meta?: any): void {
+    const formatted = this.format(level, msg, meta);
+    if (this.config.logDest === "stdout") {
+      console.error(formatted);
+    } else {
+      fs.appendFileSync(this.config.logFile, formatted + "\n");
+    }
+  }
+}

package/src/Server.ts

@@ -0,0 +1,274 @@
+import { Server as SDKServer } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import fs from "node:fs";
+import path from "node:path";
+import { Config } from "./Config.js";
+import { Logger } from "./Logger.js";
+import { Tools } from "./Tools.js";
+import safeJsonStringify from "json-stringify-safe";
+
+export class Server {
+  private static instance: Server | null = null;
+
+  static getInstance(): Server {
+    if (!Server.instance) {
+      Server.instance = new Server();
+    }
+    return Server.instance;
+  }
+
+  private server = new SDKServer(
+    { name: "trinity", version: "0.1.0" },
+    {
+      capabilities: {
+        tools: { listChanged: true },
+        resources: { listChanged: true },
+      },
+    },
+  );
+
+  private constructor(
+    private logger = new Logger(Server),
+    private config = Config.getInstance(),
+    private tools = Tools.getInstance(),
+  ) {
+    this.registerHandlers();
+    this.tools.onChange(() => this.onToolsChanged());
+  }
+
+  async start(): Promise<void> {
+    this.logger.info(`Starting server in`, {
+      mode: this.config.mode,
+      targetFolder: this.config.targetFolder,
+      glob: this.config.glob,
+      port: this.config.port,
+    });
+
+    this.tools.startWatching();
+
+    const transport = await this.createTransport();
+    await this.server.connect(transport);
+
+    await this.server.sendToolListChanged();
+
+    await this.server.sendResourceListChanged();
+
+    this.logger.info("Server started successfully");
+  }
+
+  async stop(): Promise<void> {
+    this.logger.info("Stopping server...");
+    this.tools.stopWatching();
+    await this.server.close();
+    this.logger.info("Server stopped");
+  }
+
+  private registerHandlers(): void {
+    this.server.setRequestHandler(ListToolsRequestSchema, async () =>
+      this.handleListTools(),
+    );
+
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) =>
+      this.handleCallTool(request),
+    );
+
+    this.server.setRequestHandler(ListResourcesRequestSchema, async () =>
+      this.handleListResources(),
+    );
+
+    this.server.setRequestHandler(ReadResourceRequestSchema, async (request) =>
+      this.handleReadResource(request),
+    );
+  }
+
+  private async handleListTools() {
+    this.logger.debug("Handling list_tools request");
+
+    const toolDefs = await this.tools.loadTools();
+
+    const tools = toolDefs.map((tool) => {
+      // Convert Zod schema to JSON Schema for the MCP protocol
+      const jsonSchema = tool.inputSchema.toJSONSchema();
+
+      this.logger.debug(`Generated JSON schema for tool`, {
+        name: tool.name,
+        jsonSchema,
+      });
+
+      return {
+        name: tool.name,
+        description: tool.description,
+        inputSchema: jsonSchema as {
+          type: "object";
+          properties?: Record<string, unknown>;
+          required?: string[];
+        },
+      };
+    });
+
+    this.logger.debug(`Returning ${tools.length} tools`);
+    return { tools };
+  }
+
+  private async handleCallTool(request: {
+    params: { name: string; arguments?: Record<string, unknown> };
+  }) {
+    const { name, arguments: args } = request.params;
+    this.logger.info(`Calling tool: ${name}`);
+
+    try {
+      const tool = await this.tools.loadTool(name);
+      const raw = await tool.execute(args || {});
+      this.logger.debug(`Tool ${name} executed successfully`, { raw });
+
+      return this.formatToolResult(raw);
+    } catch (err) {
+      this.logger.error(`Tool ${name} execution failed`, err as Error);
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Error: ${(err as Error).message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  }
+
+  private formatToolResult(raw: any) {
+    // Handle arrays: each item becomes a content item
+    if (Array.isArray(raw)) {
+      return { content: raw.map((item) => this.formatContentItem(item)) };
+    }
+
+    // Handle objects with MCP content types (image, audio, resource_link, resource)
+    if (raw && typeof raw === "object") {
+      return {
+        content: [{ type: "text", text: safeJsonStringify(raw, null, 2) }],
+        structuredContent: raw,
+      };
+    }
+
+    return { content: [{ type: "text", text: String(raw) }] };
+  }
+
+  private formatContentItem(item: any): any {
+    // If it's already an MCP content item, return as-is
+    if (item && typeof item === "object" && "type" in item) {
+      return item;
+    }
+
+    // Otherwise, convert to text
+    const text =
+      typeof item === "string"
+        ? item
+        : item === null || item === undefined
+          ? String(item)
+          : typeof item === "object"
+            ? JSON.stringify(item, null, 2)
+            : String(item);
+
+    return { type: "text", text };
+  }
+
+  private async createTransport(): Promise<Transport> {
+    if (this.config.mode === "stdio") {
+      this.logger.info("Using stdio transport");
+      return new StdioServerTransport();
+    }
+
+    this.logger.info(`Starting HTTP server on port ${this.config.port}`);
+    return this.createHttpTransport();
+  }
+
+  private async createHttpTransport(): Promise<Transport> {
+    // Use WebStandardStreamableHTTPServerTransport — works natively with Bun's fetch API
+    const { WebStandardStreamableHTTPServerTransport } =
+      await import("@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js");
+
+    const transport = new WebStandardStreamableHTTPServerTransport({
+      sessionIdGenerator: () => crypto.randomUUID(),
+    });
+
+    Bun.serve({
+      port: this.config.port,
+      fetch: async (req: Request): Promise<Response> => {
+        const url = new URL(req.url);
+
+        if (url.pathname === "/mcp") {
+          return await transport.handleRequest(req);
+        }
+
+        if (url.pathname === "/health") {
+          return new Response(JSON.stringify({ status: "ok" }), {
+            headers: { "Content-Type": "application/json" },
+          });
+        }
+
+        return new Response("Not Found", { status: 404 });
+      },
+    });
+
+    this.logger.info(`HTTP server listening on port ${this.config.port}`);
+    return transport;
+  }
+
+  private async handleListResources() {
+    this.logger.debug("Handling list_resources request");
+
+    const resources = [
+      {
+        uri: "trinity://docs/tools",
+        name: "How to implement/define Tools",
+        description:
+          "Comprehensive guide for creating and managing tools with Trinity MCP, including schemas, hot reload, and best practices",
+        mimeType: "text/markdown",
+      },
+    ];
+
+    this.logger.debug(`Returning ${resources.length} resources`);
+    return { resources };
+  }
+
+  private async handleReadResource(request: { params: { uri: string } }) {
+    const { uri } = request.params;
+    this.logger.info(`Reading resource: ${uri}`);
+
+    if (uri === "trinity://docs/tools") {
+      try {
+        const docsPath = path.resolve(import.meta.dir, "../docs/TOOLS.md");
+        const content = fs.readFileSync(docsPath, "utf-8");
+
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: "text/markdown",
+              text: content,
+            },
+          ],
+        };
+      } catch (err) {
+        this.logger.error(`Failed to read resource ${uri}`, err as Error);
+        throw new Error(`Failed to read resource: ${(err as Error).message}`);
+      }
+    }
+
+    throw new Error(`Resource not found: ${uri}`);
+  }
+
+  private onToolsChanged(): void {
+    this.logger.info("Tools changed, notifying clients");
+    this.server.sendToolListChanged().catch((err: Error) => {
+      this.logger.error("Failed to send tool list changed notification", err);
+    });
+  }
+}

package/src/Tools.ts

@@ -0,0 +1,165 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Glob } from "bun";
+import { Config } from "./Config.js";
+import { Logger } from "./Logger.js";
+import { ZodType } from "zod";
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: ZodType;
+  execute: (args: Record<string, unknown>) => Promise<any>;
+}
+
+export class Tools {
+  private static instance: Tools | null = null;
+
+  static getInstance(): Tools {
+    if (!Tools.instance) {
+      Tools.instance = new Tools();
+    }
+    return Tools.instance;
+  }
+
+  private watcher: fs.FSWatcher | null = null;
+  private onChangeCallback: (() => void) | null = null;
+
+  private constructor(
+    private logger = new Logger(Tools),
+    private config = Config.getInstance()
+  ) {}
+
+  async loadTools(): Promise<ToolDefinition[]> {
+    const files = await this.resolveToolFiles();
+    this.logger.debug(`Resolved ${files.length} tool files`);
+
+    const tools: ToolDefinition[] = [];
+
+    for (const filePath of files) {
+      try {
+        const tool = await this.loadToolFromFile(filePath);
+        tools.push(tool);
+      } catch (err) {
+        this.logger.error(`Failed to load tool from ${filePath}`, err as Error);
+      }
+    }
+
+    return tools;
+  }
+
+  async loadTool(name: string): Promise<ToolDefinition> {
+    const files = await this.resolveToolFiles();
+    const filePath = files.find(
+      (f) => path.basename(f, path.extname(f)) === name
+    );
+
+    if (!filePath) {
+      throw new Error(`Tool not found: ${name}`);
+    }
+
+    return this.loadToolFromFile(filePath);
+  }
+
+  onChange(callback: () => void): void {
+    this.onChangeCallback = callback;
+  }
+
+  startWatching(): void {
+    const targetFolder = this.config.targetFolder;
+    this.logger.info(`Watching for changes in ${targetFolder}`);
+
+    this.watcher = fs.watch(
+      targetFolder,
+      { recursive: true },
+      (event: string, filename: string | null) => {
+        if (filename) {
+          this.onFileChange(event, filename);
+        }
+      }
+    );
+
+    this.watcher.on("error", (err: Error) => {
+      this.logger.error("Watcher error", err);
+    });
+  }
+
+  stopWatching(): void {
+    if (this.watcher) {
+      this.watcher.close();
+      this.watcher = null;
+      this.logger.info("Stopped watching for changes");
+    }
+  }
+
+  private async resolveToolFiles(): Promise<string[]> {
+    const glob = new Glob(this.config.glob);
+    const targetFolder = this.config.targetFolder;
+    const files: string[] = [];
+
+    for await (const file of glob.scan({ cwd: targetFolder, absolute: true })) {
+      files.push(file);
+    }
+
+    return files;
+  }
+
+  private async loadToolFromFile(filePath: string): Promise<ToolDefinition> {
+    const mod = await this.dynamicImport(filePath);
+    const name = path.basename(filePath, path.extname(filePath));
+
+    if (!mod.description || typeof mod.description !== "string") {
+      throw new Error(
+        `Tool file ${filePath} must export a 'description' string`
+      );
+    }
+
+    if (!mod.inputSchema || typeof mod.inputSchema !== "object") {
+      throw new Error(
+        `Tool file ${filePath} must export an 'inputSchema' object`
+      );
+    }
+
+    if (!mod.default || typeof mod.default !== "function") {
+      throw new Error(
+        `Tool file ${filePath} must have a default export function (execute)`
+      );
+    }
+
+    return {
+      name,
+      description: this.buildDescription(mod.description, filePath),
+      inputSchema: mod.inputSchema as ZodType,
+      execute: mod.default as ToolDefinition["execute"],
+    };
+  }
+
+  private async dynamicImport(filePath: string): Promise<Record<string, unknown>> {
+    // Cache-busting with timestamp to always get fresh module
+    return import(`${filePath}?t=${Date.now()}`);
+  }
+
+  private buildDescription(description: string, filePath: string): string {
+    return [
+      description,
+      "",
+      "---",
+      `Source: ${filePath}`,
+      "Note: This tool is dynamically loaded. Changes to this file will immediately affect this tool's behavior. You can read and modify this file to change the tool.",
+    ].join("\n");
+  }
+
+  private onFileChange(event: string, filename: string): void {
+    // Check if the changed file matches our glob pattern
+    const glob = new Glob(this.config.glob);
+    if (!glob.match(filename)) {
+      return;
+    }
+
+    this.logger.info(`File ${event}: ${filename}`);
+
+    if (this.onChangeCallback) {
+      this.onChangeCallback();
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env bun
+
+import { Config } from "./Config.js";
+import { Server } from "./Server.js";
+import { Logger } from "./Logger.js";
+
+const logger = new Logger("main");
+
+try {
+  Config.getInstance().parse(process.argv.slice(2));
+} catch (err) {
+  console.error((err as Error).message);
+  console.error("Usage: bun --hot src/index.ts --target <path> [--glob <pattern>] [--port <number>]");
+  process.exit(1);
+}
+
+const server = Server.getInstance();
+
+process.on("SIGINT", async () => {
+  logger.info("Received SIGINT, shutting down...");
+  await server.stop();
+  process.exit(0);
+});
+
+process.on("SIGTERM", async () => {
+  logger.info("Received SIGTERM, shutting down...");
+  await server.stop();
+  process.exit(0);
+});
+
+try {
+  await server.start();
+} catch (err) {
+  logger.error("Failed to start server", err as Error);
+  process.exit(1);
+}