feat: add experimental decorator sample file and support for roots

Author: zcaceres

README.md

@@ -1,13 +1,18 @@
 # easy-mcp
 
-> EasyMCP is in beta, with a first release coming in January 2025. Please report any issues you encounter.
+> EasyMCP is usable but in beta. Please report any issues you encounter.
 
 Easy MCP is the simplest way to create Model Context Protocol (MCP) servers in TypeScript.
 
-It hides the plumbing and definitions behind simple, easy-to-use functions, allowing you to focus on building your server. Easy MCP strives to mimic the syntax of popular server frameworks like Express, making it easy to get started.
+It hides the plumbing, formatting, and other boilerplate definitions behind simple decorators that wrap a function.
 
 Easy MCP allows you to define the bare minimum of what you need to get started, or you can define more complex resources, templates, tools, and prompts.
 
+## Features
+
+- Define @Tools, @Prompts, @Resources, and @Roots with one call to a decorator. Every possible parameter that could be optional is optional and hidden unless you need it.
+- Automagically infers tool, prompt, and resource arguments. No input schema definition required!
+
 ## Installation
 
 To install easy-mcp, run the following command in your project directory:
@@ -24,10 +29,71 @@ bun add easy-mcp
 
 ## Limitations
 
-- No support for sampling
-- No support for SSE
+- No support for logging, yet
+- No support for sampling, yet
+- No support for SSE, yet
+
+## Usage with Decorator API
+
+This API is simpler and infers types and input configuration automatically. But it's experimental.
+
+```typescript
+import EasyMCP from "./EasyMCP";
+import { Prompt } from "./decorators/Prompt";
+import { Resource } from "./decorators/Resource";
+import { Root } from "./decorators/Root";
+import { Tool } from "./decorators/Tool";
+
+@Root({
+  uri: "/my-sample-dir/photos",
+})
+@Root({
+  uri: "/my-root-dir",
+  name: "My laptop's root directory",
+})
+class ZachsMCP extends EasyMCP {
+  @Tool({})
+  addNum(name: string, age: number) {
+    return `${name} of ${age} age`;
+  }
+
+  @Tool({
+    description: "A function with various parameter types",
+    optionalParameters: ["active", "items", "age"],
+  })
+  exampleFunc(name: string, active?: string, items?: string[], age?: number) {
+    return `exampleFunc called: name ${name}, active ${active}, items ${items}, age ${age}`;
+  }
+
+  @Resource({
+    uri: "hello-world",
+  })
+  helloWorld() {
+    return "Hello, world!";
+  }
+
+  @Resource({
+    uriTemplate: "greeting/{name}",
+  })
+  greeting(name: string) {
+    return `Hello, ${name}!`;
+  }
+
+  @Prompt({
+    name: "prompt test",
+    description: "test",
+  })
+  myPrompt(name: string) {
+    return `Prompting... ${name}`;
+  }
+}
+
+const mcp = new ZachsMCP({ version: "1.0.0" });
+console.log(mcp.name, "is now serving!");
+```
+
 
-## Usage
+## Usage with Express-like API
 
 Here's a basic example of how to use easy-mcp:
 

lib/SKETCH.ts example-experimental-decorators.ts

@@ -1,16 +1,20 @@
-import EasyMCP from "./EasyMCP";
-import { Prompt } from "./decorators/Prompt";
-import { Resource } from "./decorators/Resource";
-import { Root } from "./decorators/Root";
-import { Tool } from "./decorators/Tool";
+import EasyMCP from "./lib/EasyMCP";
+import { Prompt } from "./lib/decorators/Prompt";
+import { Resource } from "./lib/decorators/Resource";
+import { Root } from "./lib/decorators/Root";
+import { Tool } from "./lib/decorators/Tool";
 
 @Root({
-  uri: "my sample root",
+  uri: "/my-sample-dir/photos",
+})
+@Root({
+  uri: "/my-root-dir",
+  name: "My laptop's root directory",
 })
 class ZachsMCP extends EasyMCP {
   @Tool({})
-  addNum({ name, age }: { name: string; age: number }) {
-    console.log(`${name} of ${age} age`);
+  addNum(name: string, age: number) {
+    return `${name} of ${age} age`;
   }
 
   @Tool({
@@ -45,12 +49,4 @@ class ZachsMCP extends EasyMCP {
 }
 
 const mcp = new ZachsMCP({ version: "1.0.0" });
-
-mcp.root({
-  uri: "/",
-  resource: "hello",
-});
-
-mcp.serve();
-
-console.dir(mcp);
+console.log(mcp.name, "is now serving!");

lib/EasyMCP.ts

@@ -267,6 +267,14 @@ export default class EasyMCP extends BaseMCP {
     super("", { version, description });
     this.name = this.constructor.name;
 
+    // Handle class-level Root decorators
+    const rootConfigs = (this.constructor as any).rootConfigs;
+    if (rootConfigs && Array.isArray(rootConfigs)) {
+      rootConfigs.forEach((rootConfig) => {
+        this.root(rootConfig);
+      });
+    }
+
     const childMethods = Object.getOwnPropertyNames(Object.getPrototypeOf(this))
       .filter((method) => typeof this[method] === "function")
       .filter(
@@ -278,30 +286,36 @@ export default class EasyMCP extends BaseMCP {
 
     childMethods.forEach((method) => {
       // Assuming the decorator has been run to wrap these functions, we should have one of these configs on the relevant method.
+      // @ts-expect-error Due to decorator behavior we're doing some JS prototype hacking that triggers a TS error here
       if (this[method][metadataKey].toolConfig) {
+        // @ts-expect-error Due to decorator behavior we're doing some JS prototype hacking that triggers a TS error here
         this.tool(this[method][metadataKey].toolConfig);
       }
 
+      // @ts-expect-error Due to decorator behavior we're doing some JS prototype hacking that triggers a TS error here
       if (this[method][metadataKey].promptConfig) {
+        // @ts-expect-error Due to decorator behavior we're doing some JS prototype hacking that triggers a TS error here
         this.prompt(this[method][metadataKey].promptConfig);
       }
-
+      // @ts-expect-error Due to decorator behavior we're doing some JS prototype hacking that triggers a TS error here
       if (this[method][metadataKey].rootConfig) {
+        // @ts-expect-error Due to decorator behavior we're doing some JS prototype hacking that triggers a TS error here
         this.root(this[method][metadataKey].rootConfig);
       }
 
+      // @ts-expect-error Due to decorator behavior we're doing some JS prototype hacking that triggers a TS error here
       if (this[method][metadataKey].resourceConfig) {
+        // @ts-expect-error Due to decorator behavior we're doing some JS prototype hacking that triggers a TS error here
         this.resource(this[method][metadataKey].resourceConfig);
       }
 
+      // @ts-expect-error Due to decorator behavior we're doing some JS prototype hacking that triggers a TS error here
       if (this[method][metadataKey].resourceTemplateConfig) {
+        // @ts-expect-error Due to decorator behavior we're doing some JS prototype hacking that triggers a TS error here
         this.template(this[method][metadataKey].resourceTemplateConfig);
       }
     });
 
-    console.log("EasyMCP created with tools:", this.toolManager.list());
-
-    // Start serving
-    // this.serve();
+    this.serve();
   }
 }

lib/decorators/Root.ts

@@ -1,33 +1,21 @@
-import type { Root } from "@modelcontextprotocol/sdk/types.js";
-import { metadataKey } from "../MagicConfig";
-
-export function Root(config: { uri: string }) {
-  return function (
-    target: any,
-    propertyKey: string,
-    descriptor: PropertyDescriptor,
-  ) {
-    const originalMethod = descriptor.value;
-
-    const rootConfig: Root = {
-      name: propertyKey,
-      uri: config.uri,
-    };
-
-    /**
-    We add the Root configuration to the original method so that it lives on the functions prototype.
-
-    When we instantiate the class later, we have access to this config which we can then use to register the Root with the Root Manager.
-    */
-
-    if (!originalMethod[metadataKey]) {
-      originalMethod[metadataKey] = {};
+/**
+ * All other decorators wrap instance methods. This decorator wraps the class itself because Roots do not have logic or function params when they're fulfilled.
+ */
+export function Root(config: { uri: string; name?: string }) {
+  return function <T extends { new (...args: any[]): {} }>(constructor: T) {
+    if (!constructor.hasOwnProperty("rootConfigs")) {
+      Object.defineProperty(constructor, "rootConfigs", {
+        value: [],
+        writable: true,
+        configurable: true,
+      });
     }
 
-    if (rootConfig) {
-      originalMethod[metadataKey].rootConfig = rootConfig;
-    }
+    (constructor as any).rootConfigs.push({
+      uri: config.uri,
+      name: config.name || constructor.name,
+    });
 
-    return descriptor;
+    return constructor;
   };
 }

package.json

@@ -4,6 +4,7 @@
   "type": "module",
   "scripts": {
     "start": "bun run index.ts",
+    "start:decorators": "bun run example-experimental-decorators.ts",
     "dev": "bun --watch index.ts"
   },
   "devDependencies": {