@mctx-ai/mcp-server 0.3.0

package/dist/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/dist/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 };
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@mctx-ai/mcp-server",
+  "version": "0.3.0",
+  "description": "Build MCP servers with an Express-like API — no protocol knowledge required",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "types": "./src/index.d.ts"
+    }
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "anthropic",
+    "claude",
+    "server",
+    "framework"
+  ],
+  "author": "mctx, Inc.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mctx-ai/mcp-server.git",
+    "directory": "packages/server"
+  },
+  "bugs": {
+    "url": "https://github.com/mctx-ai/mcp-server/issues"
+  },
+  "homepage": "https://docs.mctx.ai",
+  "devDependencies": {
+    "@eslint/js": "^9.19.0",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^9.19.0",
+    "typescript": "^5.7.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "mkdir -p dist && cp src/*.js src/*.d.ts dist/",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/ test/",
+    "lint:fix": "eslint src/ test/ --fix",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/completion.js

@@ -0,0 +1,214 @@
+/**
+ * Completion Support Module
+ *
+ * Generates auto-completion suggestions for prompts, resources, and tool arguments.
+ * Supports custom completion handlers and auto-generation from schema metadata.
+ *
+ * @module completion
+ */
+
+/**
+ * Maximum number of completion results to return
+ */
+const MAX_COMPLETIONS = 100;
+
+/**
+ * Generates completion suggestions for a reference
+ *
+ * Handles completion for:
+ * - Prompt arguments (ref/prompt-argument)
+ * - Resources (ref/resource)
+ *
+ * Supports:
+ * - Custom .complete() handler on registered items
+ * - Auto-generation from T.enum() values
+ * - Auto-generation from resource URI templates
+ *
+ * @param {Object} registeredItems - Map of registered prompts/resources
+ * @param {Object} ref - Reference object with type and name/uri
+ * @param {string} argumentValue - Partial text to complete against
+ * @returns {Object} Completion result: { completion: { values: [...], hasMore: boolean } }
+ *
+ * @example
+ * // Custom completion handler
+ * const items = {
+ *   'list-customers': {
+ *     complete: async (argName, partialValue) => {
+ *       if (argName === 'status') {
+ *         return ['active', 'inactive', 'pending'];
+ *       }
+ *       return [];
+ *     }
+ *   }
+ * };
+ *
+ * generateCompletions(items, { type: 'ref/prompt-argument', name: 'list-customers' }, 'act')
+ * // => { completion: { values: ['active'], hasMore: false } }
+ *
+ * @example
+ * // Auto-generation from T.enum
+ * const items = {
+ *   'search': {
+ *     input: {
+ *       status: T.string({ enum: ['pending', 'active', 'completed'] })
+ *     }
+ *   }
+ * };
+ *
+ * generateCompletions(items, { type: 'ref/prompt-argument', name: 'search' }, 'p')
+ * // => { completion: { values: ['pending'], hasMore: false } }
+ */
+export function generateCompletions(registeredItems, ref, argumentValue) {
+  // Validate inputs
+  if (!registeredItems || typeof registeredItems !== "object") {
+    return createEmptyCompletion();
+  }
+
+  if (!ref || !ref.type) {
+    return createEmptyCompletion();
+  }
+
+  const partialValue = argumentValue || "";
+
+  // Handle prompt argument completion
+  if (ref.type === "ref/prompt-argument") {
+    return generatePromptArgumentCompletions(
+      registeredItems,
+      ref,
+      partialValue,
+    );
+  }
+
+  // Handle resource completion
+  if (ref.type === "ref/resource") {
+    return generateResourceCompletions(registeredItems, ref, partialValue);
+  }
+
+  // Unknown reference type
+  return createEmptyCompletion();
+}
+
+/**
+ * Generate completions for prompt arguments
+ * @private
+ */
+function generatePromptArgumentCompletions(registeredItems, ref, partialValue) {
+  const promptName = ref.name;
+  if (!promptName) return createEmptyCompletion();
+
+  const prompt = registeredItems[promptName];
+  if (!prompt) return createEmptyCompletion();
+
+  // Check for custom completion handler
+  if (typeof prompt.complete === "function") {
+    return executeCustomCompletion(
+      prompt.complete,
+      ref.argumentName,
+      partialValue,
+    );
+  }
+
+  // Auto-generate from T.enum values if available
+  if (prompt.input && ref.argumentName) {
+    const schema = prompt.input[ref.argumentName];
+    if (schema && schema.enum && Array.isArray(schema.enum)) {
+      return filterAndCap(schema.enum, partialValue);
+    }
+  }
+
+  return createEmptyCompletion();
+}
+
+/**
+ * Generate completions for resources
+ * @private
+ */
+function generateResourceCompletions(registeredItems, ref, partialValue) {
+  const uri = ref.uri;
+  if (!uri) return createEmptyCompletion();
+
+  const resource = registeredItems[uri];
+  if (!resource) return createEmptyCompletion();
+
+  // Check for custom completion handler
+  if (typeof resource.complete === "function") {
+    return executeCustomCompletion(resource.complete, null, partialValue);
+  }
+
+  // Auto-generate from URI templates
+  // Extract possible values from template variables (limited - this is basic)
+  // In practice, custom handlers are recommended for dynamic resources
+
+  return createEmptyCompletion();
+}
+
+/**
+ * Execute custom completion handler
+ * @private
+ */
+function executeCustomCompletion(completeFn, argumentName, partialValue) {
+  try {
+    const result = completeFn(argumentName, partialValue);
+
+    // Async completion handlers are not supported
+    if (result instanceof Promise) {
+      throw new Error(
+        "Async completion handlers are not supported. Use synchronous handlers for fn.complete.",
+      );
+    }
+
+    // Filter and cap the results
+    if (Array.isArray(result)) {
+      return filterAndCap(result, partialValue);
+    }
+
+    return createEmptyCompletion();
+  } catch (error) {
+    console.error("Completion handler error:", error);
+    return createEmptyCompletion();
+  }
+}
+
+/**
+ * Filter completion values by partial match and cap at MAX_COMPLETIONS
+ * @private
+ * @param {Array<string>} values - All possible values
+ * @param {string} partialValue - User's partial input
+ * @returns {Object} Completion result
+ */
+function filterAndCap(values, partialValue) {
+  if (!Array.isArray(values)) {
+    return createEmptyCompletion();
+  }
+
+  // Filter values that start with partial input (case-insensitive)
+  const lowerPartial = partialValue.toLowerCase();
+  const filtered = values.filter((value) => {
+    if (typeof value !== "string") return false;
+    return value.toLowerCase().startsWith(lowerPartial);
+  });
+
+  // Cap at MAX_COMPLETIONS
+  const hasMore = filtered.length > MAX_COMPLETIONS;
+  const capped = filtered.slice(0, MAX_COMPLETIONS);
+
+  return {
+    completion: {
+      values: capped,
+      hasMore,
+    },
+  };
+}
+
+/**
+ * Create empty completion result
+ * @private
+ */
+function createEmptyCompletion() {
+  return {
+    completion: {
+      values: [],
+      hasMore: false,
+    },
+  };
+}