@metorial/mcp-server 1.0.0-rc.1

package/src/adapter.ts

@@ -0,0 +1,167 @@
+import z from 'zod';
+import { McpServerInstance } from './instance';
+
+let discoverMessage = z.object({
+  type: z.literal('metorial-mcp.discover')
+});
+type DiscoverMessage = z.infer<typeof discoverMessage>;
+
+let authUrlMessage = z.object({
+  type: z.literal('metorial-mcp.get-oauth-authorization-url'),
+  params: z.object({
+    authConfig: z.record(z.string(), z.any()),
+    clientId: z.string(),
+    clientSecret: z.string(),
+    state: z.string(),
+    redirectUri: z.string()
+  })
+});
+type AuthUrlMessage = z.infer<typeof authUrlMessage>;
+
+let oauthCallbackMessage = z.object({
+  type: z.literal('metorial-mcp.handle-oauth-callback'),
+  params: z.object({
+    authConfig: z.record(z.string(), z.any()),
+    authState: z.record(z.string(), z.string()),
+    clientId: z.string(),
+    clientSecret: z.string(),
+    code: z.string(),
+    state: z.string(),
+    redirectUri: z.string(),
+    callbackUrl: z.string(),
+    authorizationUrl: z.string()
+  })
+});
+type OauthCallbackMessage = z.infer<typeof oauthCallbackMessage>;
+
+let oauthTokenRefreshMessage = z.object({
+  type: z.literal('metorial-mcp.handle-oauth-token-refresh'),
+  params: z.object({
+    authConfig: z.record(z.string(), z.any()),
+    authState: z.record(z.string(), z.string()),
+    refreshToken: z.string(),
+    clientId: z.string(),
+    clientSecret: z.string()
+  })
+});
+type OauthTokenRefreshMessage = z.infer<typeof oauthTokenRefreshMessage>;
+
+let allMessages = z.union([
+  discoverMessage,
+  authUrlMessage,
+  oauthCallbackMessage,
+  oauthTokenRefreshMessage
+]);
+
+export type McpServerInstanceMessage =
+  | DiscoverMessage
+  | AuthUrlMessage
+  | OauthCallbackMessage
+  | OauthTokenRefreshMessage;
+
+export let serverAdapter = async (
+  instance: McpServerInstance,
+  messages: McpServerInstanceMessage[]
+) =>
+  Promise.all(
+    messages.map(async message => {
+      let parsed = allMessages.parse(message);
+
+      switch (parsed.type) {
+        case 'metorial-mcp.discover': {
+          return instance.discover();
+        }
+        case 'metorial-mcp.get-oauth-authorization-url': {
+          return instance.getOauthAuthorizationUrl(parsed.params);
+        }
+        case 'metorial-mcp.handle-oauth-callback': {
+          return instance.handleOauthCallback(parsed.params);
+        }
+        case 'metorial-mcp.handle-oauth-token-refresh': {
+          return instance.handleOauthTokenRefresh(parsed.params);
+        }
+      }
+
+      throw new Error(`Unknown message type: ${(message as any).type}`);
+    })
+  );
+
+export type McpServerInstanceAdapterResponses = Awaited<ReturnType<typeof serverAdapter>>;
+
+export let clientAdapter = (
+  transport: (
+    messages: McpServerInstanceMessage[]
+  ) => Promise<McpServerInstanceAdapterResponses>
+) => {
+  let queue: {
+    msg: McpServerInstanceMessage;
+    resolve: (res: any) => void;
+    reject: (err: any) => void;
+  }[] = [];
+  let isSent = { current: false };
+  let isSending = { current: false };
+
+  let send = async (message: McpServerInstanceMessage) => {
+    let promise = new Promise<any>((resolve, reject) => {
+      queue.push({ msg: message, resolve, reject });
+    });
+
+    if (!isSending.current) {
+      isSending.current = true;
+
+      setTimeout(async () => {
+        isSent.current = true;
+
+        try {
+          let res = await transport(queue.map(q => q.msg));
+          res.forEach((r, i) => {
+            queue[i].resolve(r);
+          });
+        } catch (err) {
+          queue.forEach(q => {
+            q.reject(err);
+          });
+        } finally {
+          queue = [];
+        }
+      }, 2);
+    }
+
+    return promise;
+  };
+
+  return {
+    discover: async () => {
+      return send({ type: 'metorial-mcp.discover' }) as Promise<
+        Awaited<ReturnType<McpServerInstance['discover']>>
+      >;
+    },
+
+    getOauthAuthorizationUrl: async (
+      d: Parameters<McpServerInstance['getOauthAuthorizationUrl']>[0]
+    ) => {
+      return send({
+        type: 'metorial-mcp.get-oauth-authorization-url',
+        params: d
+      }) as Promise<Awaited<ReturnType<McpServerInstance['getOauthAuthorizationUrl']>>>;
+    },
+
+    handleOauthCallback: async (
+      d: Parameters<McpServerInstance['handleOauthCallback']>[0]
+    ) => {
+      return send({
+        type: 'metorial-mcp.handle-oauth-callback',
+        params: d
+      }) as Promise<Awaited<ReturnType<McpServerInstance['handleOauthCallback']>>>;
+    },
+
+    handleOauthTokenRefresh: async (
+      d: Parameters<McpServerInstance['handleOauthTokenRefresh']>[0]
+    ) => {
+      return send({
+        type: 'metorial-mcp.handle-oauth-token-refresh',
+        params: d
+      }) as Promise<Awaited<ReturnType<McpServerInstance['handleOauthTokenRefresh']>>>;
+    }
+  };
+};

package/src/auth.ts

@@ -0,0 +1,165 @@
+import z from 'zod';
+
+export type McpServerAuthUrlHandlerParams<AuthConfig extends {}> = {
+  authConfig: AuthConfig;
+  clientId: string;
+  clientSecret: string;
+  state: string;
+  redirectUri: string;
+};
+
+export type McpServerAuthUrlHandlerResult = {
+  authorizationUrl: string;
+  authState?: Record<string, string> | null;
+};
+
+export type McpServerAuthUrlHandlerInternal = <AuthConfig extends {}>(
+  d: McpServerAuthUrlHandlerParams<AuthConfig>
+) => Promise<McpServerAuthUrlHandlerResult>;
+
+export type McpServerAuthUrlHandler = <AuthConfig extends {}>(
+  d: McpServerAuthUrlHandlerParams<AuthConfig>
+) => Promise<string | McpServerAuthUrlHandlerResult>;
+
+export type McpServerAuthCallbackHandlerParams<AuthConfig extends {}> = {
+  authConfig: AuthConfig;
+  authState: Record<string, string>;
+  clientId: string;
+  clientSecret: string;
+  code: string;
+  state: string;
+  redirectUri: string;
+  callbackUrl: string;
+  authorizationUrl: string;
+};
+
+export type McpServerAuthCallbackHandlerResult = {
+  accessToken: string;
+  refreshToken?: string;
+  expiresIn?: number;
+  scope?: string;
+  tokenType?: string;
+  [key: string]: any;
+};
+
+export type McpServerAuthCallbackHandler = <AuthConfig extends {}>(
+  d: McpServerAuthCallbackHandlerParams<AuthConfig>
+) => Promise<McpServerAuthCallbackHandlerResult>;
+
+export type McpServerAuthTokenRefreshHandlerParams<AuthConfig extends {}> = {
+  authConfig: AuthConfig;
+  authState: Record<string, string>;
+  refreshToken: string;
+  clientId: string;
+  clientSecret: string;
+};
+
+export type McpServerAuthTokenRefreshHandlerResult = {
+  accessToken: string;
+  refreshToken?: string;
+  expiresIn?: number;
+  scope?: string;
+  tokenType?: string;
+  [key: string]: any;
+};
+
+export type McpServerAuthTokenRefreshHandler = <AuthConfig extends {}>(
+  d: McpServerAuthTokenRefreshHandlerParams<AuthConfig>
+) => Promise<McpServerAuthTokenRefreshHandlerResult>;
+
+export type McpServerAuthValue = {
+  accessToken: string;
+  expiresIn?: number;
+  scope?: string;
+  tokenType?: string;
+  [key: string]: any;
+};
+
+export class McpServerAuthConfig<AuthConfig extends {}> {
+  #value: McpServerAuthValue | null = null;
+
+  #getAuthUrlHandler?: McpServerAuthUrlHandlerInternal;
+  #callbackHandler?: McpServerAuthCallbackHandler;
+  #tokenRefreshHandler?: McpServerAuthTokenRefreshHandler;
+
+  private constructor(private readonly schema: z.ZodType<AuthConfig>) {}
+
+  static create<AuthConfig extends {}>(schema?: z.ZodType<AuthConfig>) {
+    return new McpServerAuthConfig(schema ?? (z.object({}) as z.ZodType<AuthConfig>));
+  }
+
+  static getImplementation(config: McpServerAuthConfig<any>) {
+    if (!config.#getAuthUrlHandler || !config.#callbackHandler) {
+      throw new Error('MCP Server auth config is missing required handlers');
+    }
+
+    return {
+      getAuthUrlHandler: config.#getAuthUrlHandler,
+      callbackHandler: config.#callbackHandler,
+      tokenRefreshHandler: config.#tokenRefreshHandler
+    };
+  }
+
+  setValue(value: McpServerAuthValue) {
+    this.#value = value;
+  }
+
+  getAuthorizationUrl(cb: McpServerAuthUrlHandler) {
+    this.#getAuthUrlHandler = async d => {
+      let res = await cb(d);
+      if (typeof res == 'string') {
+        return { authorizationUrl: res };
+      }
+      return res;
+    };
+    return this;
+  }
+
+  handleCallback(cb: McpServerAuthCallbackHandler) {
+    this.#callbackHandler = cb;
+    return this;
+  }
+
+  refreshToken(cb: McpServerAuthTokenRefreshHandler) {
+    this.#tokenRefreshHandler = cb;
+    return this;
+  }
+
+  build(): AuthConfig {
+    if (!this.#getAuthUrlHandler || !this.#callbackHandler) {
+      throw new Error('MCP Server auth config is missing required handlers');
+    }
+
+    let self = this;
+
+    // Proxy for getting the config values
+    // or throwing an error if not set
+    return new Proxy(
+      {},
+      {
+        get: (target, prop, receiver) => {
+          if (prop == '__config__') {
+            return self;
+          }
+
+          if (self.#value === null) {
+            throw new Error('MCP Server auth config value not set');
+          }
+
+          return (self.#value as any)[prop];
+        }
+      }
+    ) as any as AuthConfig;
+  }
+}
+
+export let createAuth = <Config extends {}>(schema?: z.ZodType<Config>) => {
+  return McpServerAuthConfig.create(schema);
+};
+
+export let auth = <Config extends {}>(schema?: z.ZodType<Config>) => createAuth(schema);
+
+export let getAuthConfigImplementation = <Config extends {}>(configValue: any) => {
+  let self = configValue['__config__'] as McpServerAuthConfig<Config>;
+  return McpServerAuthConfig.getImplementation(self);
+};

package/src/client.ts

@@ -0,0 +1,69 @@
+import { createInMemoryTransport } from '@metorial/mcp-transport-memory';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import {
+  ClientCapabilities,
+  JSONRPCMessage,
+  Notification
+} from '@modelcontextprotocol/sdk/types.js';
+import z from 'zod';
+
+export interface ClientOpts {
+  client: {
+    name: string;
+    version: string;
+  };
+  capabilities: ClientCapabilities;
+}
+
+export let getClient = async (
+  server: McpServer,
+  notificationListener: (notification: Notification) => Promise<void>,
+  opts: ClientOpts
+) => {
+  let transport = createInMemoryTransport();
+  await server.connect(transport.server);
+
+  let client = new Client(opts.client);
+
+  client.registerCapabilities(opts.capabilities);
+  client.fallbackNotificationHandler = notificationListener;
+
+  await client.connect(transport.client);
+
+  return client;
+};
+
+export let handleMcpMessages = async (
+  server: McpServer,
+  opts: ClientOpts,
+  messages: JSONRPCMessage[]
+) => {
+  let responses: JSONRPCMessage[] = [];
+
+  let client = await getClient(
+    server,
+    async notification => {
+      responses.push(notification as JSONRPCMessage);
+    },
+    opts
+  );
+
+  let error: Error | null = null;
+
+  for (let message of messages) {
+    try {
+      if ('id' in message) {
+        let res = await client.request(message as any, z.any());
+        responses.push(res);
+      } else {
+        await client.notification(message as any);
+      }
+    } catch (err) {
+      error = err as Error;
+      break;
+    }
+  }
+
+  return { messages: responses, error };
+};

package/src/config.ts

@@ -0,0 +1,68 @@
+import z from 'zod';
+
+export class McpServerConfig<Config extends {}> {
+  #value: Config | null = null;
+
+  private constructor(public readonly schema: z.ZodType<Config>) {}
+
+  static create<Config extends {}>(schema: z.ZodType<Config>) {
+    return new McpServerConfig(schema);
+  }
+
+  setValue(value: unknown) {
+    let parsed = this.schema.parse(value);
+    this.#value = parsed;
+  }
+
+  value(): Config {
+    let self = this;
+
+    // Proxy for getting the config values
+    // or throwing an error if not set
+    return new Proxy(
+      {},
+      {
+        get: (target, prop, receiver) => {
+          if (prop == '__config__') {
+            return self;
+          }
+
+          if (self.#value === null) {
+            throw new Error('MCP Server config value not set');
+          }
+
+          return (self.#value as any)[prop];
+        }
+      }
+    ) as any as Config;
+  }
+}
+
+export let createConfig = <Config extends {}>(schema: z.ZodType<Config>) => {
+  return McpServerConfig.create(schema).value();
+};
+
+export let config = <Config extends {}>(schema: z.ZodType<Config>) => createConfig(schema);
+
+export let setConfigValue = <Config extends {}>(configValue: any, value: Config) => {
+  let self = configValue['__config__'] as McpServerConfig<Config>;
+  self.setValue(value);
+};
+
+export let getConfigSchema = <Config extends {}>(configValue: any) => {
+  let self = configValue['__config__'] as McpServerConfig<Config>;
+  return self.schema.toJSONSchema({
+    unrepresentable: 'any',
+    override: ctx => {
+      let def = ctx.zodSchema._zod.def;
+
+      if (def.type === 'date') {
+        ctx.jsonSchema.type = 'string';
+        ctx.jsonSchema.format = 'date-time';
+      }
+      if (def.type === 'bigint') {
+        ctx.jsonSchema.type = 'number';
+      }
+    }
+  });
+};

package/src/index.ts

@@ -0,0 +1,32 @@
+export {
+  createMcpServer,
+  type McpServerInstance,
+  type McpServerInstanceOpts,
+  type McpServerInstanceServer
+} from './instance';
+
+export {
+  clientAdapter,
+  serverAdapter,
+  type McpServerInstanceAdapterResponses,
+  type McpServerInstanceMessage
+} from './adapter';
+
+export {
+  auth,
+  createAuth,
+  type McpServerAuthCallbackHandler,
+  type McpServerAuthCallbackHandlerParams,
+  type McpServerAuthCallbackHandlerResult,
+  type McpServerAuthConfig,
+  type McpServerAuthTokenRefreshHandler,
+  type McpServerAuthTokenRefreshHandlerParams,
+  type McpServerAuthTokenRefreshHandlerResult,
+  type McpServerAuthUrlHandler,
+  type McpServerAuthUrlHandlerInternal,
+  type McpServerAuthUrlHandlerParams,
+  type McpServerAuthUrlHandlerResult,
+  type McpServerAuthValue
+} from './auth';
+
+export { config, createConfig, type McpServerConfig } from './config';

package/src/instance.ts

@@ -0,0 +1,90 @@
+import {
+  createMcpServer as createMcpServerInternal,
+  CreateMcpServerOpts
+} from '@metorial/mcp';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp';
+import { JSONRPCMessage } from '@modelcontextprotocol/sdk/types';
+import {
+  getAuthConfigImplementation,
+  McpServerAuthCallbackHandlerParams,
+  McpServerAuthTokenRefreshHandlerParams,
+  McpServerAuthUrlHandlerParams
+} from './auth';
+import { ClientOpts, handleMcpMessages } from './client';
+import { getConfigSchema, setConfigValue } from './config';
+
+export type McpServerInstanceServer = CreateMcpServerOpts | { server: McpServer };
+let getServer = (instance: McpServerInstanceServer) => {
+  if ('server' in instance) {
+    return instance.server;
+  } else {
+    return createMcpServerInternal(instance);
+  }
+};
+
+export type McpServerInstanceOpts = McpServerInstanceServer & {
+  config?: any;
+  authConfig?: any;
+};
+
+export class McpServerInstance {
+  #server: McpServer;
+
+  private constructor(private instance: McpServerInstanceOpts) {
+    this.#server = getServer(instance);
+  }
+
+  static create(instance: McpServerInstanceOpts) {
+    return new McpServerInstance(instance);
+  }
+
+  discover() {
+    return {
+      configSchema: this.instance.config ? getConfigSchema(this.instance.config) : null,
+      oauth: this.instance.authConfig
+        ? {
+            status: 'enabled' as const,
+            hasTokenRefresh: !!getAuthConfigImplementation(this.instance.authConfig)
+              .tokenRefreshHandler
+          }
+        : {
+            status: 'disabled' as const
+          }
+    };
+  }
+
+  handleMcpMessages(opts: { config: any; client: ClientOpts; message: JSONRPCMessage[] }) {
+    setConfigValue(this.instance.config, opts.config);
+
+    return handleMcpMessages(this.#server, opts.client, opts.message);
+  }
+
+  getOauthAuthorizationUrl(d: McpServerAuthUrlHandlerParams<any>) {
+    if (!this.instance.authConfig) return null;
+    let impl = getAuthConfigImplementation(this.instance.authConfig);
+
+    return impl.getAuthUrlHandler(d);
+  }
+
+  handleOauthCallback(d: McpServerAuthCallbackHandlerParams<any>) {
+    if (!this.instance.authConfig) return null;
+    let impl = getAuthConfigImplementation(this.instance.authConfig);
+
+    return impl.callbackHandler(d);
+  }
+
+  handleOauthTokenRefresh(d: McpServerAuthTokenRefreshHandlerParams<any>) {
+    if (!this.instance.authConfig) return null;
+    let impl = getAuthConfigImplementation(this.instance.authConfig);
+
+    if (!impl.tokenRefreshHandler) {
+      return null;
+    }
+
+    return impl.tokenRefreshHandler(d);
+  }
+}
+
+export let createMcpServer = (instance: McpServerInstanceOpts) => {
+  return McpServerInstance.create(instance);
+};