@mctx-ai/mcp-server 0.3.0

package/src/types.js

@@ -0,0 +1,252 @@
+/**
+ * T - JSON Schema type system for MCP tool and prompt inputs
+ *
+ * Provides factory methods to build JSON Schema objects with a clean API.
+ * Supports type validation, constraints, and nested schemas.
+ */
+
+/**
+ * Creates a string type schema
+ * @param {Object} options - Schema options
+ * @param {boolean} [options.required] - Mark field as required (metadata for buildInputSchema)
+ * @param {string} [options.description] - Field description
+ * @param {Array} [options.enum] - Allowed values
+ * @param {*} [options.default] - Default value
+ * @param {number} [options.minLength] - Minimum string length
+ * @param {number} [options.maxLength] - Maximum string length
+ * @param {string} [options.pattern] - Regex pattern
+ * @param {string} [options.format] - Format (email, uri, date-time, etc.)
+ * @returns {Object} JSON Schema object
+ */
+function string(options = {}) {
+  const schema = { type: "string" };
+
+  if (options.description !== undefined)
+    schema.description = options.description;
+  if (options.enum !== undefined) schema.enum = options.enum;
+  if (options.default !== undefined) schema.default = options.default;
+  if (options.minLength !== undefined) schema.minLength = options.minLength;
+  if (options.maxLength !== undefined) schema.maxLength = options.maxLength;
+  if (options.pattern !== undefined) schema.pattern = options.pattern;
+  if (options.format !== undefined) schema.format = options.format;
+
+  // Store required as metadata (not a JSON Schema keyword on properties)
+  if (options.required === true) schema._required = true;
+
+  return schema;
+}
+
+/**
+ * Creates a number type schema
+ * @param {Object} options - Schema options
+ * @param {boolean} [options.required] - Mark field as required (metadata for buildInputSchema)
+ * @param {string} [options.description] - Field description
+ * @param {Array} [options.enum] - Allowed values
+ * @param {*} [options.default] - Default value
+ * @param {number} [options.min] - Minimum value (maps to 'minimum')
+ * @param {number} [options.max] - Maximum value (maps to 'maximum')
+ * @returns {Object} JSON Schema object
+ */
+function number(options = {}) {
+  const schema = { type: "number" };
+
+  if (options.description !== undefined)
+    schema.description = options.description;
+  if (options.enum !== undefined) schema.enum = options.enum;
+  if (options.default !== undefined) schema.default = options.default;
+  if (options.min !== undefined) schema.minimum = options.min;
+  if (options.max !== undefined) schema.maximum = options.max;
+
+  if (options.required === true) schema._required = true;
+
+  return schema;
+}
+
+/**
+ * Creates a boolean type schema
+ * @param {Object} options - Schema options
+ * @param {boolean} [options.required] - Mark field as required (metadata for buildInputSchema)
+ * @param {string} [options.description] - Field description
+ * @param {*} [options.default] - Default value
+ * @returns {Object} JSON Schema object
+ */
+function boolean(options = {}) {
+  const schema = { type: "boolean" };
+
+  if (options.description !== undefined)
+    schema.description = options.description;
+  if (options.default !== undefined) schema.default = options.default;
+
+  if (options.required === true) schema._required = true;
+
+  return schema;
+}
+
+/**
+ * Creates an array type schema
+ * @param {Object} options - Schema options
+ * @param {boolean} [options.required] - Mark field as required (metadata for buildInputSchema)
+ * @param {string} [options.description] - Field description
+ * @param {Object} [options.items] - Schema for array items
+ * @param {*} [options.default] - Default value
+ * @returns {Object} JSON Schema object
+ */
+function array(options = {}) {
+  const schema = { type: "array" };
+
+  if (options.description !== undefined)
+    schema.description = options.description;
+  if (options.default !== undefined) schema.default = options.default;
+  if (options.items !== undefined) {
+    // Clean _required metadata from items schema
+    schema.items = cleanMetadata(options.items);
+  }
+
+  if (options.required === true) schema._required = true;
+
+  return schema;
+}
+
+/**
+ * Creates an object type schema
+ * @param {Object} options - Schema options
+ * @param {boolean} [options.required] - Mark field as required (metadata for buildInputSchema)
+ * @param {string} [options.description] - Field description
+ * @param {Object} [options.properties] - Nested property schemas
+ * @param {boolean|Object} [options.additionalProperties] - Allow additional properties
+ * @param {*} [options.default] - Default value
+ * @returns {Object} JSON Schema object
+ */
+function object(options = {}) {
+  const schema = { type: "object" };
+
+  if (options.description !== undefined)
+    schema.description = options.description;
+  if (options.default !== undefined) schema.default = options.default;
+
+  // Handle nested properties
+  if (options.properties !== undefined) {
+    const { properties, required } = buildProperties(options.properties);
+    schema.properties = properties;
+    if (required.length > 0) schema.required = required;
+  }
+
+  if (options.additionalProperties !== undefined) {
+    if (typeof options.additionalProperties === "boolean") {
+      schema.additionalProperties = options.additionalProperties;
+    } else {
+      // Clean metadata from additionalProperties schema
+      schema.additionalProperties = cleanMetadata(options.additionalProperties);
+    }
+  }
+
+  if (options.required === true) schema._required = true;
+
+  return schema;
+}
+
+/**
+ * Builds properties object and extracts required fields
+ * Helper for buildInputSchema and object()
+ * @param {Object} properties - Properties map
+ * @returns {{properties: Object, required: Array<string>}} Cleaned properties and required array
+ */
+function buildProperties(properties) {
+  if (!properties || typeof properties !== "object") {
+    return { properties: {}, required: [] };
+  }
+
+  const cleanedProperties = {};
+  const required = [];
+
+  for (const [key, schema] of Object.entries(properties)) {
+    if (!schema || typeof schema !== "object") continue;
+
+    // Extract required metadata
+    if (schema._required === true) {
+      required.push(key);
+    }
+
+    // Clean the schema (remove metadata)
+    cleanedProperties[key] = cleanMetadata(schema);
+  }
+
+  return { properties: cleanedProperties, required };
+}
+
+/**
+ * Removes framework metadata from schema
+ * @param {Object} schema - Schema object
+ * @returns {Object} Cleaned schema
+ */
+function cleanMetadata(schema) {
+  if (!schema || typeof schema !== "object") return schema;
+
+  // Create shallow copy
+  const cleaned = { ...schema };
+
+  // Remove metadata
+  delete cleaned._required;
+
+  // Recursively clean nested schemas
+  if (cleaned.properties && typeof cleaned.properties === "object") {
+    const { properties, required } = buildProperties(cleaned.properties);
+    cleaned.properties = properties;
+    if (required.length > 0) cleaned.required = required;
+  }
+
+  if (cleaned.items && typeof cleaned.items === "object") {
+    cleaned.items = cleanMetadata(cleaned.items);
+  }
+
+  if (
+    cleaned.additionalProperties &&
+    typeof cleaned.additionalProperties === "object"
+  ) {
+    cleaned.additionalProperties = cleanMetadata(cleaned.additionalProperties);
+  }
+
+  return cleaned;
+}
+
+/**
+ * Builds a complete MCP input schema from handler input definition
+ * @param {Object} input - Handler input definition using T types
+ * @returns {Object} Valid JSON Schema for MCP inputSchema
+ */
+export function buildInputSchema(input) {
+  // Handle null/undefined input
+  if (!input) {
+    return {
+      type: "object",
+      properties: {},
+    };
+  }
+
+  // Build properties and extract required fields
+  const { properties, required } = buildProperties(input);
+
+  const schema = {
+    type: "object",
+    properties,
+  };
+
+  // Only add required array if not empty
+  if (required.length > 0) {
+    schema.required = required;
+  }
+
+  return schema;
+}
+
+/**
+ * T - Type factory object
+ * Exports all type builders
+ */
+export const T = {
+  string,
+  number,
+  boolean,
+  array,
+  object,
+};

package/src/uri.js

@@ -0,0 +1,120 @@
+/**
+ * URI Template Matching Module
+ *
+ * Implements RFC 6570 Level 1 URI templates (simple string expansion {var}).
+ * Provides utilities for matching request URIs against registered resource URIs
+ * and extracting template parameters.
+ *
+ * @module uri
+ */
+
+/**
+ * Checks if a URI contains template variables
+ * @param {string} uri - The URI to check
+ * @returns {boolean} True if URI contains {param} syntax
+ *
+ * @example
+ * isTemplate('db://customers/123')           // false
+ * isTemplate('db://customers/{id}')          // true
+ * isTemplate('db://products/{id}/reviews')   // true
+ */
+export function isTemplate(uri) {
+  if (!uri || typeof uri !== "string") return false;
+  return /\{[^}]+\}/.test(uri);
+}
+
+/**
+ * Extracts template variable names from a URI
+ * @param {string} uri - The URI template
+ * @returns {string[]} Array of variable names
+ * @throws {Error} If template variable name is invalid
+ *
+ * @example
+ * extractTemplateVars('db://customers/{id}')                    // ['id']
+ * extractTemplateVars('db://products/{category}/items/{id}')    // ['category', 'id']
+ * extractTemplateVars('db://customers/123')                     // []
+ */
+export function extractTemplateVars(uri) {
+  if (!uri || typeof uri !== "string") return [];
+
+  const matches = uri.matchAll(/\{([^}]+)\}/g);
+  const vars = [];
+
+  for (const match of matches) {
+    const varName = match[1];
+
+    // Validate: alphanumeric + underscore only (RFC 6570 Level 1)
+    if (!/^[a-zA-Z0-9_]+$/.test(varName)) {
+      throw new Error(
+        `Invalid template variable name: "${varName}". Must contain only alphanumeric characters and underscores.`,
+      );
+    }
+
+    vars.push(varName);
+  }
+
+  return vars;
+}
+
+/**
+ * Matches a request URI against a registered URI template
+ *
+ * Returns null for no match, or an object with extracted parameters for match.
+ * Handles both static URIs (exact match) and dynamic URIs (template expansion).
+ *
+ * @param {string} registeredUri - The registered URI (may contain {param} templates)
+ * @param {string} requestUri - The incoming request URI (no templates)
+ * @returns {Object|null} Match result: { params: { name: value, ... } } or null
+ *
+ * @example
+ * // Static URI - exact match
+ * matchUri('db://customers/schema', 'db://customers/schema')
+ * // => { params: {} }
+ *
+ * matchUri('db://customers/schema', 'db://customers/list')
+ * // => null
+ *
+ * // Dynamic URI - parameter extraction
+ * matchUri('db://customers/{id}', 'db://customers/123')
+ * // => { params: { id: '123' } }
+ *
+ * matchUri('db://products/{category}/items/{id}', 'db://products/electronics/items/456')
+ * // => { params: { category: 'electronics', id: '456' } }
+ *
+ * matchUri('db://customers/{id}', 'db://products/123')
+ * // => null (different path)
+ */
+export function matchUri(registeredUri, requestUri) {
+  // Guard clauses
+  if (!registeredUri || typeof registeredUri !== "string") return null;
+  if (!requestUri || typeof requestUri !== "string") return null;
+
+  // Static route: exact string match
+  if (!isTemplate(registeredUri)) {
+    return registeredUri === requestUri ? { params: {} } : null;
+  }
+
+  // Dynamic route: build regex pattern and extract params
+  const templateVars = extractTemplateVars(registeredUri);
+
+  // Escape regex special characters except {placeholders}
+  // Convert {var} to named capture group
+  let pattern = registeredUri
+    .replace(/[.*+?^${}()|[\]\\]/g, "\\$&") // Escape regex chars
+    .replace(/\\\{([^}]+)\\\}/g, "([^/]+)"); // Convert {var} to capture group
+
+  pattern = `^${pattern}$`; // Exact match (anchored)
+
+  const regex = new RegExp(pattern);
+  const match = requestUri.match(regex);
+
+  if (!match) return null;
+
+  // Extract parameters from capture groups
+  const params = {};
+  for (let i = 0; i < templateVars.length; i++) {
+    params[templateVars[i]] = match[i + 1]; // match[0] is full string, params start at [1]
+  }
+
+  return { params };
+}