@mctx-ai/mcp-server 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mctx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

package/dist/conversation.js

@@ -0,0 +1,139 @@
+/**
+ * Conversation Module - Prompt System
+ *
+ * Provides a clean builder API for constructing MCP prompt messages.
+ * Supports user and AI messages with text, images, and embedded resources.
+ *
+ * @module conversation
+ */
+
+/**
+ * Creates a conversation using a builder function
+ *
+ * @param {Function} builderFn - Function that receives { user, ai } helpers
+ * @returns {Object} MCP prompt result: { messages: [...] }
+ *
+ * @example
+ * conversation(({ user, ai }) => [
+ *   user.say("What's in this image?"),
+ *   user.attach(base64data, "image/png"),
+ *   user.embed("db://customers/schema"),
+ *   ai.say("I see a customer schema with fields: id, name, email"),
+ * ])
+ * // Returns: { messages: [{ role: "user", content: {...} }, ...] }
+ */
+export function conversation(builderFn) {
+  if (typeof builderFn !== "function") {
+    throw new Error("conversation() requires a builder function");
+  }
+
+  // Create helper objects
+  const user = createRoleHelper("user");
+  const ai = createRoleHelper("assistant");
+
+  // Execute builder function
+  const result = builderFn({ user, ai });
+
+  // Validate result is array
+  if (!Array.isArray(result)) {
+    throw new Error("Builder function must return an array of messages");
+  }
+
+  return { messages: result };
+}
+
+/**
+ * Creates a role-specific helper object with say/attach/embed methods
+ * @private
+ * @param {string} role - The role ("user" or "assistant")
+ * @returns {Object} Helper with say/attach/embed methods
+ */
+function createRoleHelper(role) {
+  return {
+    /**
+     * Add a text message
+     * @param {string} text - The text content
+     * @returns {Object} MCP message object
+     */
+    say(text) {
+      if (typeof text !== "string") {
+        throw new Error(`${role}.say() requires a string argument`);
+      }
+
+      return {
+        role,
+        content: {
+          type: "text",
+          text,
+        },
+      };
+    },
+
+    /**
+     * Attach an image (base64 data)
+     * @param {string} data - Base64-encoded image data
+     * @param {string} mimeType - MIME type (REQUIRED: e.g., "image/png", "image/jpeg")
+     * @returns {Object} MCP message object
+     * @throws {Error} If mimeType is missing
+     */
+    attach(data, mimeType) {
+      if (typeof data !== "string") {
+        throw new Error(
+          `${role}.attach() requires base64 data as first argument`,
+        );
+      }
+
+      if (mimeType === undefined || mimeType === null) {
+        throw new Error(
+          `${role}.attach() requires mimeType as second argument (e.g., "image/png")`,
+        );
+      }
+
+      if (typeof mimeType !== "string") {
+        throw new Error(
+          `${role}.attach() requires mimeType as second argument (e.g., "image/png")`,
+        );
+      }
+
+      if (!/^[a-zA-Z]+\/[a-zA-Z0-9\-+.]+$/.test(mimeType)) {
+        throw new Error(
+          `Invalid MIME type: "${mimeType}". Expected format: type/subtype (e.g., "image/png")`,
+        );
+      }
+
+      return {
+        role,
+        content: {
+          type: "image",
+          data,
+          mimeType,
+        },
+      };
+    },
+
+    /**
+     * Embed a resource by URI
+     * @param {string} uri - The resource URI to embed
+     * @returns {Object} MCP message object
+     *
+     * Note: Actual resource resolution happens at server level.
+     * This creates a placeholder with [embedded] text.
+     */
+    embed(uri) {
+      if (typeof uri !== "string") {
+        throw new Error(`${role}.embed() requires a URI string`);
+      }
+
+      return {
+        role,
+        content: {
+          type: "resource",
+          resource: {
+            uri,
+            text: "[embedded]",
+          },
+        },
+      };
+    },
+  };
+}