@ananay-nag/mcp-decorators 1.0.0

package/dist/esm/src/server/utils/serverRegistry.d.ts

@@ -0,0 +1,81 @@
+import { RegisterServerOptions, UseServerOptions } from "../types/index.js";
+/**
+ * Registers a server with the given options.
+ * Stores the server metadata in a registry.
+ * Throws an error if a server with the same name and version is already registered.
+ * @param options - Options for registering the server (name, version).
+ * @param server - The server instance to register.
+ */
+export declare function registerServer(options: RegisterServerOptions, server: any): void;
+/**
+ * Retrieves a registered server based on the provided options.
+ * Returns the server instance if found, otherwise undefined.
+ * If a version is specified, it returns the server with that specific version.
+ * If no version is specified and only one version is registered, it returns that server.
+ * Otherwise, it returns undefined.
+ * @param options - Options for retrieving the server (name, optional version).
+ * @returns The registered server instance or undefined.
+ */
+export declare function getServer(options: UseServerOptions): any | undefined;
+/**
+ * Metadata registration structure for server instances.
+ * Stores decorators data globally mapped to their respective server.
+ */
+export interface ServerRegistration {
+    server: any;
+    tools: Map<string, {
+        options: any;
+        handler: Function;
+    }>;
+    prompts: Map<string, {
+        options: any;
+        handler: Function;
+    }>;
+    resources: Map<string, {
+        options: any;
+        handler: Function;
+    }>;
+    resourceTemplates: Map<string, {
+        options: any;
+        handler: Function;
+    }>;
+    subscribers: Map<string, Set<string>>;
+    subscribeHandler?: Function;
+    unsubscribeHandler?: Function;
+    completionHandlers: Array<{
+        ref: any;
+        handler: Function;
+    }>;
+}
+/**
+ * Get or create server registration details for tracking decorator features.
+ */
+export declare function getOrCreateServerRegistration(server: any): ServerRegistration;
+/**
+ * Match a URI against a URI template and extract parameters.
+ * E.g. template: "mysql://{tableName}/schema" matches uri: "mysql://users/schema"
+ * and returns { tableName: "users" }.
+ */
+export declare function matchUriTemplate(template: string, uri: string): Record<string, string> | null;
+/**
+ * Helper to notify clients that a resource has updated.
+ */
+export declare function notifyResourceUpdated(server: any, uri: string): Promise<void>;
+/**
+ * Helper to send progress notifications to a client from a server handler.
+ */
+export declare function sendProgress(server: any, progressToken: string | number, progress: number, total?: number, message?: string): Promise<void>;
+/**
+ * Helper to send logging messages/notifications from a server.
+ */
+export declare function sendLoggingMessage(server: any, level: "debug" | "info" | "notice" | "warning" | "error" | "critical" | "alert" | "emergency", data: unknown, logger?: string): Promise<void>;
+/**
+ * Helper to request elicitation (input/form) from the client.
+ */
+export declare function elicitInput(server: any, params: {
+    mode: "form" | "url";
+    message?: string;
+    requestedSchema?: Record<string, unknown>;
+    url?: string;
+}, options?: any): Promise<any>;
+//# sourceMappingURL=serverRegistry.d.ts.map

package/dist/esm/src/server/utils/serverRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverRegistry.d.ts","sourceRoot":"","sources":["../../../../../src/server/utils/serverRegistry.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,mBAAmB,CAAC;AAK3B;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,qBAAqB,EAC9B,MAAM,EAAE,GAAG,GACV,IAAI,CAgBN;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,GAAG,GAAG,SAAS,CAqBpE;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,GAAG,CAAC;IACZ,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,GAAG,CAAC;QAAC,OAAO,EAAE,QAAQ,CAAA;KAAE,CAAC,CAAC;IACxD,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,GAAG,CAAC;QAAC,OAAO,EAAE,QAAQ,CAAA;KAAE,CAAC,CAAC;IAC1D,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,GAAG,CAAC;QAAC,OAAO,EAAE,QAAQ,CAAA;KAAE,CAAC,CAAC;IAC5D,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,GAAG,CAAC;QAAC,OAAO,EAAE,QAAQ,CAAA;KAAE,CAAC,CAAC;IACpE,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACtC,gBAAgB,CAAC,EAAE,QAAQ,CAAC;IAC5B,kBAAkB,CAAC,EAAE,QAAQ,CAAC;IAC9B,kBAAkB,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,GAAG,CAAC;QAAC,OAAO,EAAE,QAAQ,CAAA;KAAE,CAAC,CAAC;CAC5D;AAID;;GAEG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,GAAG,GAAG,kBAAkB,CAe7E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAoB7F;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMnF;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,GAAG,EACX,aAAa,EAAE,MAAM,GAAG,MAAM,EAC9B,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAWf;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,GAAG,EACX,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,WAAW,EAC7F,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAUf;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,GAAG,EACX,MAAM,EAAE;IACN,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,EACD,OAAO,CAAC,EAAE,GAAG,GACZ,OAAO,CAAC,GAAG,CAAC,CAUd"}

package/dist/esm/src/server/utils/serverRegistry.js

@@ -0,0 +1,140 @@
+import { z } from "zod";
+const serverRegistry = new Map();
+/**
+ * Registers a server with the given options.
+ * Stores the server metadata in a registry.
+ * Throws an error if a server with the same name and version is already registered.
+ * @param options - Options for registering the server (name, version).
+ * @param server - The server instance to register.
+ */
+export function registerServer(options, server) {
+    const { name, version } = options;
+    const serverMetadata = { name, version, server };
+    const existingServers = serverRegistry.get(name) || [];
+    const alreadyRegistered = existingServers.some((s) => s.version === version);
+    if (alreadyRegistered) {
+        throw new Error(`Server with name "${name}" and version "${version}" is already registered.`);
+    }
+    serverRegistry.set(name, [...existingServers, serverMetadata]);
+}
+/**
+ * Retrieves a registered server based on the provided options.
+ * Returns the server instance if found, otherwise undefined.
+ * If a version is specified, it returns the server with that specific version.
+ * If no version is specified and only one version is registered, it returns that server.
+ * Otherwise, it returns undefined.
+ * @param options - Options for retrieving the server (name, optional version).
+ * @returns The registered server instance or undefined.
+ */
+export function getServer(options) {
+    const { name, version } = options;
+    const serverMetadataList = serverRegistry.get(name);
+    if (!serverMetadataList || serverMetadataList.length === 0) {
+        return undefined;
+    }
+    if (version) {
+        const foundServer = serverMetadataList.find((s) => s.version === version);
+        return foundServer === null || foundServer === void 0 ? void 0 : foundServer.server;
+    }
+    if (serverMetadataList.length === 1) {
+        return serverMetadataList[0].server;
+    }
+    if (!version) {
+        console.log(`Server version not passed, will return same name version ${serverMetadataList[0].name} with index 0 found in registry.`);
+    }
+    return serverMetadataList[0].server; // No specific version requested and multiple versions exist
+}
+const activeServers = new Map();
+/**
+ * Get or create server registration details for tracking decorator features.
+ */
+export function getOrCreateServerRegistration(server) {
+    let reg = activeServers.get(server);
+    if (!reg) {
+        reg = {
+            server,
+            tools: new Map(),
+            prompts: new Map(),
+            resources: new Map(),
+            resourceTemplates: new Map(),
+            subscribers: new Map(),
+            completionHandlers: [],
+        };
+        activeServers.set(server, reg);
+    }
+    return reg;
+}
+/**
+ * Match a URI against a URI template and extract parameters.
+ * E.g. template: "mysql://{tableName}/schema" matches uri: "mysql://users/schema"
+ * and returns { tableName: "users" }.
+ */
+export function matchUriTemplate(template, uri) {
+    const paramNames = [];
+    const regexStr = "^" + template
+        .replace(/[.+*?^$()|[\]\\\/\s]/g, "\\$&") // Escape regex special chars except {}
+        .replace(/\{([^}]+)\}/g, (_, name) => {
+        paramNames.push(name);
+        return "([^/]+)";
+    }) + "$";
+    const regex = new RegExp(regexStr);
+    const match = uri.match(regex);
+    if (!match) {
+        return null;
+    }
+    const params = {};
+    for (let i = 0; i < paramNames.length; i++) {
+        params[paramNames[i]] = match[i + 1];
+    }
+    return params;
+}
+/**
+ * Helper to notify clients that a resource has updated.
+ */
+export async function notifyResourceUpdated(server, uri) {
+    const underlyingServer = server.server || server;
+    await underlyingServer.notification({
+        method: "notifications/resources/updated",
+        params: { uri }
+    });
+}
+/**
+ * Helper to send progress notifications to a client from a server handler.
+ */
+export async function sendProgress(server, progressToken, progress, total, message) {
+    const underlyingServer = server.server || server;
+    await underlyingServer.notification({
+        method: "notifications/progress",
+        params: {
+            progressToken,
+            progress,
+            total,
+            message
+        }
+    });
+}
+/**
+ * Helper to send logging messages/notifications from a server.
+ */
+export async function sendLoggingMessage(server, level, data, logger) {
+    const underlyingServer = server.server || server;
+    await underlyingServer.notification({
+        method: "notifications/message",
+        params: {
+            level,
+            data,
+            logger
+        }
+    });
+}
+/**
+ * Helper to request elicitation (input/form) from the client.
+ */
+export async function elicitInput(server, params, options) {
+    const underlyingServer = server.server || server;
+    return underlyingServer.request({
+        method: "elicitation/create",
+        params
+    }, z.any(), options);
+}
+//# sourceMappingURL=serverRegistry.js.map

package/dist/esm/src/server/utils/serverRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverRegistry.js","sourceRoot":"","sources":["../../../../../src/server/utils/serverRegistry.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@ananay-nag/mcp-decorators",
+  "version": "1.0.0",
+  "description": "Model Context Protocol implementation for TypeScript with decorators",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/cjs/index.d.ts",
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    },
+    "./*": {
+      "import": "./dist/esm/*",
+      "require": "./dist/cjs/*"
+    }
+  },
+  "files": [
+    "dist",
+    "banner.svg"
+  ],
+  "scripts": {
+    "build:esm": "mkdir -p dist/esm && echo '{\"type\": \"module\"}' > dist/esm/package.json && tsc -p tsconfig.prod.json",
+    "build:esm:w": "npm run build:esm -- -w",
+    "build:cjs": "mkdir -p dist/cjs && echo '{\"type\": \"commonjs\"}' > dist/cjs/package.json && tsc -p tsconfig.cjs.json",
+    "build:cjs:w": "npm run build:cjs -- -w",
+    "build": "npm run build:esm && npm run build:cjs",
+    "build:publish": "rm -rf dist/ *mcp*.tgz && npm run build && npm pack"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.11.0",
+    "zod": "^3.23.8",
+    "zod-to-json-schema": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.4"
+  },
+  "homepage": "https://mcp-decorators-doc.vercel.app/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ananay-nag/mcp-decorators.git"
+  }
+}