kleanmcp 1.0.1

package/src/types.ts

@@ -0,0 +1,165 @@
+export * from "elysia-jsonrpc/mcp";
+export * from "elysia-jsonrpc/rpc";
+export * from "elysia-jsonrpc";
+
+export type ParamType =
+  | "string"
+  | "number"
+  | "boolean"
+  | "object"
+  | "Record<string, any>";
+
+export type ParamDef = {
+  type: ParamType;
+  required?: boolean;
+  default?: ParamDef["type"];
+  name: string;
+  description: string;
+};
+
+export type ExtractType<T extends ParamDef["type"]> = T extends "string"
+  ? string
+  : T extends "number"
+    ? number
+    : T extends "boolean"
+      ? boolean
+      : T extends "object"
+        ? object
+        : T extends "Record<string, any>"
+          ? Record<string, any>
+          : never;
+
+export type MethodResult<
+  TResult,
+  TParams extends readonly ParamDef[],
+  TExtra = any,
+> = {
+  name: string;
+  params: TParams;
+  callback: (...args: [...ParamsToTuple<TParams>, TExtra]) => Promise<TResult>;
+};
+
+export type NamedParam<N extends string, T extends ParamDef> = T & { name: N };
+
+export type ParamsToTuple<T extends readonly ParamDef[]> = {
+  [K in keyof T]: T[K] extends ParamDef ? ExtractType<T[K]["type"]> : never;
+};
+export type NamedParamsToTuple<
+  T extends readonly NamedParam<string, ParamDef>[],
+> = {
+  [K in keyof T]: T[K] extends NamedParam<string, infer P>
+    ? P extends ParamDef
+      ? ExtractType<P["type"]>
+      : never
+    : never;
+};
+
+export interface PropertyDescription {
+  type: string;
+  description: string;
+}
+
+export interface InputSchemaType {
+  [x: string]: unknown;
+  type: "object";
+  properties?: Record<string, PropertyDescription>;
+  required?: string[];
+}
+
+export type ToolParameterDefinition = {
+  required: boolean;
+  type: string;
+  description: string;
+  default?: object;
+};
+
+export interface CallToolResult {
+  content: any[];
+  isError?: boolean;
+}
+
+export function InputSchemaFromParameters(
+  params: ToolParameterDefinition[],
+): InputSchemaType {
+  return {
+    type: "object",
+    properties: Object.fromEntries(
+      Object.entries(params).map(([k, v]) => [
+        k,
+        {
+          description: v.description,
+          type: v.type,
+          default: v.default,
+        } as PropertyDescription,
+      ]),
+    ) as Record<string, PropertyDescription>,
+    required: Object.entries(params)
+      .map(([k, v]) => (v.required ? k : undefined))
+      .filter((v): v is string => v !== undefined),
+  } as InputSchemaType;
+}
+export function ToolArgsToParameterList<
+  TParams extends readonly NamedParam<string, ParamDef>[] = [],
+>(toolArgs: Record<string, any>, params: TParams): (any | undefined)[] {
+  let res: any[] = [];
+  for (const param of params) {
+    res.push(toolArgs[param.name] ?? param.default ?? undefined);
+  }
+  return res;
+}
+
+export type ToolDefinitionCreator<
+  ReferencedServerType,
+  TParams extends readonly NamedParam<string, ParamDef>[] = [],
+> = <UserRef extends ReferencedServerType, TExtra = any>(
+  callback: (
+    ...args: [UserRef, ...NamedParamsToTuple<TParams>, TExtra?]
+  ) => Promise<CallToolResult>,
+) => any;
+
+export function ToolDefinition<
+  ReferencedServerType = any,
+  TParams extends readonly NamedParam<string, ParamDef>[] = [],
+>(methodName: string, methodDescription: string, params: TParams): ToolDefinitionCreator<ReferencedServerType, TParams> {
+  return <UserRef extends ReferencedServerType, TExtra = any>(
+    callback: (
+      ...args: [UserRef, ...NamedParamsToTuple<TParams>, TExtra?]
+    ) => Promise<CallToolResult>,
+  ) => {
+    return {
+      name: methodName,
+      description: methodDescription,
+      params,
+      callback,
+    };
+  };
+}
+
+export type ToolDefinitionGeneric<
+  ReferencedServerType = any,
+  // TParams extends readonly NamedParam<string, ParamDef>[] = [],
+  TParams = any,
+> = {
+  name: string;
+  description: string;
+  params: TParams;
+  callback: (
+    argfirst: ReferencedServerType,
+    ...args: any[]
+  ) => Promise<CallToolResult>;
+};
+
+export interface ToolResult {
+  content: PropertyDescription[]; // TODO: maybe change
+}
+
+export interface Tool {
+  name: string;
+  description: string;
+  inputSchema: InputSchemaType;
+}
+
+export interface ToolSet {
+  getTools(): ToolDefinitionGeneric[];
+  getTool(toolName: string): ToolDefinitionGeneric | undefined;
+}

package/test/mcp.test.ts

@@ -0,0 +1,65 @@
+
+
+
+import { describe, expect, it, test } from "bun:test";
+import { MCPServerService } from "../src";
+import { TestToolSet } from "./testToolSet";
+
+describe("MCPServerService", () => {
+  const serverService = new MCPServerService(
+    "testServerTitle",
+    "1.0.0",
+    "No instructions",
+    (toolName: string) => { return serverService },
+    [
+      new TestToolSet(),
+    ]
+  );
+
+  test("that the server has the tools", async () => {
+    const toolsListResult = await serverService["tools/list"]({});
+    expect(toolsListResult.tools).toBeArrayOfSize(2);
+    expect(toolsListResult.tools.at(0)?.name).toBe("tool_name_1");
+    expect(toolsListResult.tools.at(1)?.name).toBe("tool_name_2");
+  });
+
+  test("that the server has callable tools that works without args", async () => {
+    const toolsListResult = await serverService["tools/call"]({
+      name: "tool_name_1"
+    });
+    expect(toolsListResult.isError).toBeFalse();
+    expect(toolsListResult.content).toBeArrayOfSize(1)
+    expect(toolsListResult.content[0]).toBeObject();
+    expect(toolsListResult.content[0]?.type).toBe("text");
+    expect(toolsListResult.content[0]?.text).toBe(undefined);
+  });
+
+  test("that the server has callable tools that works with args", async () => {
+    const toolsListResult = await serverService["tools/call"]({
+      name: "tool_name_1",
+      arguments: {
+        "arg1": "any"
+      }
+    });
+    expect(toolsListResult.isError).toBeFalse();
+    expect(toolsListResult.content).toBeArrayOfSize(1)
+    expect(toolsListResult.content[0]).toBeObject();
+    expect(toolsListResult.content[0]?.type).toBe("text");
+    expect(toolsListResult.content[0]?.text).toBe("any");
+  });
+
+  test("that the server has callable tools that works with arg name validation", async () => {
+    const toolsListResult = await serverService["tools/call"]({
+      name: "tool_name_1",
+      arguments: {
+        "arg0": "any"
+      }
+    });
+    expect(toolsListResult.isError).toBeFalse();
+    expect(toolsListResult.content).toBeArrayOfSize(1)
+    expect(toolsListResult.content[0]).toBeObject();
+    expect(toolsListResult.content[0]?.type).toBe("text");
+    expect(toolsListResult.content[0]?.text).toBe(undefined); // since we dont have the correct argument name
+  });
+
+});

package/test/testToolSet.ts

@@ -0,0 +1,67 @@
+import {
+  ToolDefinition,
+  type CallToolResult,
+  type ToolDefinitionGeneric,
+  type ToolSet,
+} from "../src/types";
+
+export const Tool1 = ToolDefinition(
+  "tool_name_1",
+  "this tool is a test tool 1",
+  [
+    {
+      name: "arg1",
+      description: "describing arg1",
+      type: "string",
+      required: false,
+    },
+  ] as const,
+)(async (
+  _reference: object,
+  arg_string: string,
+  _extra?: any,
+): Promise<CallToolResult> => {
+  return {
+    content: [
+      {
+        type: "text",
+        text: arg_string,
+      },
+    ],
+  };
+});
+
+export const Tool2 = ToolDefinition(
+  "tool_name_2",
+  "this tool is a test tool 2",
+  [
+    {
+      name: "arg1",
+      description: "describing arg1",
+      type: "string",
+      required: false,
+    },
+    {
+      name: "arg2",
+      description: "describing arg2",
+      type: "boolean",
+      required: false,
+    },
+  ] as const,
+)(async (
+  _reference: any,
+  arg1: string,
+  arg2: boolean,
+  _extra?: any,
+): Promise<CallToolResult> => {
+  throw new Error("this always fails");
+});
+
+export class TestToolSet implements ToolSet {
+  getTools(): ToolDefinitionGeneric[] {
+    return [Tool1, Tool2];
+  }
+  getTool(toolName: string): ToolDefinitionGeneric | undefined {
+    return this.getTools().find(x => x.name == toolName);
+  }
+}

package/test/toolset.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it, test } from "bun:test";
+import { TestToolSet } from "./testToolSet";
+
+
+describe("TestToolSet", () => {
+  const toolSet = new TestToolSet();
+  test("that the toolset can handle any name", async () => {
+    expect(toolSet.getTool("tool_name_1")).not.toBeUndefined();
+  });
+  const tools = toolSet.getTools();
+  for (const toolId in tools) {
+    const tool = tools[toolId];
+    if (!tool) continue;
+    test(`that the toolset ${toolId} is constructed correctly`, async () => {
+      expect(tool.name).toBeOneOf(["tool_name_1", "tool_name_2"]);
+      expect(tool.description).not.toBe("");
+      expect(tool.params).toBeArray();
+      expect(tool.params).not.toBeArrayOfSize(0);
+      expect(tool.params.length).toBeOneOf([1, 2]);
+    });
+    // test(`that the toolset ${i} is callable with any amount of args`, async () => {
+    const callback = tool.callback;
+    const args = [this, "test", false, "test"];
+
+    for (let n = 0; n < args.length + 1; n++) {
+      test(`should handle ${n} args correctly `, async () => {
+        const result = await expect(async () => {
+          const xargs = args.slice(0, n);
+          const ret = await (callback as any)(...xargs);
+          expect(ret).toBeObject();
+          expect(ret.content).toBeArrayOfSize(1);
+          if(n > 1) expect(ret.content[0].text).toBe(args[1]);
+        });
+        if (toolId == "0") {
+          result.not.toThrow();
+        } else if (toolId == "1") {
+          result.toThrow("this always fails");
+        }
+      });
+    }
+  }
+});

package/tsconfig.dts.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "outDir": "./dist",
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "noCheck": true,
+  },
+  "exclude": ["node_modules", "test", "src/**/*.d.ts"],
+  "include": ["src/**/*.ts"]
+}

package/tsconfig.json

@@ -0,0 +1,36 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": false,
+    "declaration": true,
+    "declarationDir": "./out",
+    "emitDeclarationOnly": true,
+    "rootDir": "./src",
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  },
+  "include": [
+    "src/**/*.ts"
+  ]
+}