mcp-orbit 0.1.0

package/src/clients/types.ts

@@ -0,0 +1,136 @@
+/**
+ * MCP Client Types & Interfaces
+ *
+ * Shared types for mcp-orbit clients
+ * Used by both real clients and mock clients
+ */
+
+// ============================================================================
+// SERVER CONFIGURATION
+// ============================================================================
+
+export interface McpStdioServerConfig {
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+}
+
+export interface McpHttpServerConfig {
+  url: string;
+  headers?: Record<string, string>;
+  timeout?: number;
+}
+
+export type McpServerConfig = McpStdioServerConfig | McpHttpServerConfig;
+
+// ============================================================================
+// TOOLS
+// ============================================================================
+
+export interface MCPToolSchema {
+  name: string;
+  description?: string;
+  input_schema: {
+    type: "object";
+    properties?: Record<string, any>;
+    required?: string[];
+    [key: string]: any;
+  };
+  tags?: string[]; // Classification tags (filtered by the workflow, not forwarded to the LLM)
+}
+
+export interface MCPToolResponse {
+  content: MCPContent[];
+  isError?: boolean;
+  structuredContent?: unknown;
+  _meta?: {
+    resourceUri?: string;
+    cached?: boolean;
+    size?: number;
+    cacheExpiry?: number;
+    toolName?: string;
+  };
+}
+
+export interface MCPContent {
+  type: "text" | "image" | "resource";
+  text?: string;
+  data?: string;
+  mimeType?: string;
+}
+
+// ============================================================================
+// RESOURCES
+// ============================================================================
+
+export interface MCPResource {
+  uri: string;
+  name: string;
+  description?: string;
+  title?: string;
+  mimeType?: string;
+  toolset?: string;
+  scope?: string;
+}
+
+export interface MCPResourceList {
+  resources: MCPResource[];
+}
+
+export interface MCPResourceContent {
+  contents: Array<{
+    uri: string;
+    text?: string;
+    blob?: string;
+  }>;
+}
+
+// ============================================================================
+// PROMPTS
+// ============================================================================
+
+export interface MCPPromptArgument {
+  name: string;
+  description?: string;
+  required?: boolean;
+  type?: "string" | "number" | "boolean" | "array" | "object";
+}
+
+export interface MCPPrompt {
+  name: string;
+  description?: string;
+  arguments?: MCPPromptArgument[];
+}
+
+export interface MCPPromptList {
+  prompts: MCPPrompt[];
+}
+
+export interface MCPPromptMessage {
+  role: "user" | "assistant";
+  content: {
+    type: "text" | "image" | "resource";
+    text?: string;
+    data?: string;
+    mimeType?: string;
+  };
+}
+
+export interface MCPPromptResponse {
+  messages: MCPPromptMessage[];
+}
+
+// ============================================================================
+// CLIENT INTERFACE
+// ============================================================================
+
+export interface IMcpClient {
+  listTools(timeoutMs?: number): Promise<{tools: MCPToolSchema[]}>;
+  callTool(toolName: string, args: Record<string, any>, timeoutMs?: number): Promise<MCPToolResponse>;
+  listResources(timeoutMs?: number): Promise<MCPResourceList>;
+  readResource(uri: string, timeoutMs?: number): Promise<MCPResourceContent>;
+  listPrompts(timeoutMs?: number): Promise<MCPPromptList>;
+  getPrompt(name: string, args?: Record<string, any>, timeoutMs?: number): Promise<MCPPromptResponse>;
+  close(): Promise<void>;
+}

package/src/core/prompt-registry.ts

@@ -0,0 +1,114 @@
+/**
+ * Prompt Registry - Simplified
+ *
+ * Auto-registration pattern with direct array access.
+ *
+ * Prompts = Templated messages & workflows for users
+ * - Chat templates with variables
+ * - Workflow assistants
+ * - Guided interactions
+ */
+
+import type {MCPPromptDefinition, PromptProvider, PromptMessage} from "./types.js";
+import logger from "../utils/logger.js";
+
+const promptLogger = logger.child("prompts");
+
+// Global prompts array - single source of truth
+const prompts: PromptProvider[] = [];
+
+/**
+ * Create and register a prompt provider
+ *
+ * Usage:
+ *   const prompt = createAndRegisterPrompt({ name, description, render: async () => ({ messages }) });
+ *
+ * This function is called during prompt module imports (auto-registration pattern)
+ */
+export function createAndRegisterPrompt(prompt: PromptProvider): PromptProvider {
+  if (prompts.some((p) => p.name === prompt.name)) {
+    promptLogger.warn(`Prompt '${prompt.name}' already registered, overwriting...`);
+  }
+
+  prompts.push(prompt);
+  promptLogger.info(`Prompt registered: ${prompt.name}`);
+  return prompt;
+}
+
+/**
+ * Get all prompt definitions (for MCP ListPrompts response)
+ */
+export function getPromptDefinitions(): MCPPromptDefinition[] {
+  return prompts.map((provider) => ({
+    name: provider.name,
+    description: provider.description,
+    arguments: provider.arguments,
+    toolset: provider.toolset,
+    tags: provider.tags,
+    category: provider.category,
+    usage: provider.usage,
+    maxTokens: provider.maxTokens,
+  }));
+}
+
+/**
+ * Get a prompt by name
+ */
+export function getPrompt(name: string): PromptProvider | undefined {
+  return prompts.find((p) => p.name === name);
+}
+
+/**
+ * Get a prompt with rendered messages (prompts/get)
+ *
+ * Handles:
+ * - Prompt lookup
+ * - Arguments validation via Zod schema
+ * - Template rendering
+ */
+export async function renderPrompt(name: string, args?: Record<string, any>): Promise<{messages: PromptMessage[]}> {
+  const prompt = getPrompt(name);
+
+  if (!prompt) {
+    throw new Error(`Prompt not found: ${name}`);
+  }
+
+  // Validate arguments if schema is provided
+  if (prompt.argumentsSchema && args) {
+    try {
+      prompt.argumentsSchema.parse(args);
+    } catch (error) {
+      throw new Error(`Invalid prompt arguments: ${String(error)}`);
+    }
+  }
+
+  // Execute prompt provider (render template)
+  const messages = await prompt.render(args);
+
+  return {messages};
+}
+
+/**
+ * Get count of registered prompts
+ */
+export function getPromptCount(): number {
+  return prompts.length;
+}
+
+/**
+ * Check if a prompt exists
+ */
+export function hasPrompt(name: string): boolean {
+  return prompts.some((p) => p.name === name);
+}
+
+/** Singleton registry object — convenience wrapper over the named exports. */
+export const promptRegistry = {
+  register: createAndRegisterPrompt,
+  listDefinitions: getPromptDefinitions,
+  get: renderPrompt,
+  get count(): number {
+    return getPromptCount();
+  },
+  has: hasPrompt,
+};

package/src/core/resource-registry.ts

@@ -0,0 +1,166 @@
+/**
+ * Resource Registry - Simplified with RFC 6570 Templates
+ *
+ * Auto-registration pattern with:
+ * - Direct array access for static resources
+ * - RFC 6570 URI template support for dynamic resources
+ */
+
+import type {MCPResource, ResourceContent, ResourceProvider} from "./types.js";
+import {TemplateRegistry} from "./resource-uri-templates.js";
+import logger from "../utils/logger.js";
+
+const resourceLogger = logger.child("resources");
+
+type RegistryContentBlock = {
+  uri: string;
+  name?: string;
+  title?: string;
+  mimeType?: string;
+  text?: string;
+  blob?: string;
+  annotations?: MCPResource["annotations"];
+  size?: number;
+  schema?: MCPResource["schema"];
+};
+
+// Global resources array - single source of truth
+const resources: ResourceProvider[] = [];
+
+// Template registry for RFC 6570 URI template support
+const templateRegistry = new TemplateRegistry();
+
+/**
+ * Create and register a resource provider
+ *
+ * Usage:
+ *   const resource = createAndRegisterResource({ uri, name, read: async () => ({ text }) });
+ *
+ * Supports both static URIs and RFC 6570 URI templates:
+ *   - Static: "cache://users/123"
+ *   - Template: "cache://users/{id}"
+ *
+ * This function is called during resource module imports (auto-registration pattern)
+ */
+export function createAndRegisterResource(resource: ResourceProvider): ResourceProvider {
+  if (resources.some((r) => r.uri === resource.uri)) {
+    resourceLogger.warn(`Resource '${resource.uri}' already registered, overwriting...`);
+  }
+
+  resources.push(resource);
+
+  if (resource.uri.includes("{")) {
+    templateRegistry.registerTemplate(resource.uri);
+    resourceLogger.info(`Resource registered (template): ${resource.uri}`);
+  } else {
+    resourceLogger.info(`Resource registered: ${resource.uri}`);
+  }
+
+  return resource;
+}
+
+/**
+ * Unregister a resource by URI (used when TTL expires)
+ */
+export function unregisterResource(uri: string): void {
+  const index = resources.findIndex((r) => r.uri === uri);
+  if (index !== -1) {
+    resources.splice(index, 1);
+    resourceLogger.info(`Resource unregistered: ${uri}`);
+  }
+}
+
+/**
+ * Get all resource definitions (for MCP ListResources response)
+ */
+export function getResourceDefinitions(): MCPResource[] {
+  return resources.map((provider) => ({
+    uri: provider.uri,
+    name: provider.name,
+    description: provider.description,
+    title: provider.title,
+    mimeType: provider.mimeType,
+    size: provider.size,
+    schema: provider.schema,
+    annotations: provider.annotations,
+    toolset: provider.toolset,
+    scope: provider.scope,
+    capabilities: provider.capabilities,
+  }));
+}
+
+/**
+ * Get a resource by URI
+ */
+export function getResource(uri: string): ResourceProvider | undefined {
+  return resources.find((r) => r.uri === uri);
+}
+
+/**
+ * Read a resource (resources/read)
+ */
+export async function readResource(uri: string): Promise<{contents: RegistryContentBlock[]}> {
+  const resource = getResource(uri);
+
+  if (!resource) {
+    throw new Error(`Resource not found: ${uri}`);
+  }
+
+  const content: ResourceContent = await resource.read();
+
+  return {
+    contents: [
+      {
+        uri: resource.uri,
+        name: resource.name,
+        title: resource.title,
+        mimeType: resource.mimeType,
+        size: resource.size,
+        schema: resource.schema,
+        annotations: resource.annotations,
+        ...content,
+      },
+    ],
+  };
+}
+
+/**
+ * Get count of registered resources
+ */
+export function getResourceCount(): number {
+  return resources.length;
+}
+
+/**
+ * Check if a resource exists
+ */
+export function hasResource(uri: string): boolean {
+  return resources.some((r) => r.uri === uri);
+}
+
+/**
+ * Get all registered RFC 6570 URI template patterns
+ */
+export function getTemplatePatterns(): string[] {
+  return templateRegistry.getTemplates();
+}
+
+/**
+ * Get template registry (for advanced template operations)
+ */
+export function getTemplateRegistry(): TemplateRegistry {
+  return templateRegistry;
+}
+
+export const resourceRegistry = {
+  register: createAndRegisterResource,
+  unregister: unregisterResource,
+  listDefinitions: getResourceDefinitions,
+  read: readResource,
+  get count(): number {
+    return getResourceCount();
+  },
+  has: hasResource,
+  getTemplates: getTemplatePatterns,
+  getTemplateRegistry,
+};

package/src/core/resource-uri-templates.ts

@@ -0,0 +1,216 @@
+/**
+ * RFC 6570 URI Template Support
+ *
+ * Implements RFC 6570 URI template matching for resource patterns.
+ * Enables pattern-based resource definitions like:
+ *   - cache://tools/{id}
+ *   - kraken://balance/{pair}
+ *
+ * See: https://tools.ietf.org/html/rfc6570
+ */
+
+/**
+ * RFC 6570 template variables with operators:
+ * - Simple expansion: {var}
+ * - Reserved expansion: {+var}
+ * - Fragment expansion: {#var}
+ * - Label expansion: {.var}
+ * - Path expansion: {/var}
+ * - Parameter expansion: {?var}
+ * - Query continuation: {&var}
+ */
+
+export interface URITemplate {
+  pattern: string;
+  regex: RegExp;
+  variables: string[];
+}
+
+export interface URIMatch {
+  matched: boolean;
+  variables: Record<string, string>;
+}
+
+/**
+ * Parse RFC 6570 URI template and create a regex matcher
+ */
+export function parseURITemplate(template: string): URITemplate {
+  // Extract all template variables: {var}, {+var}, {#var}, etc.
+  const variableRegex = /\{([+#./?&]?)([a-zA-Z_][a-zA-Z0-9_]*(?:,[a-zA-Z_][a-zA-Z0-9_]*)*)\}/g;
+  const variables: string[] = [];
+  const parts: Array<{type: "literal" | "pattern"; value: string}> = [];
+  let lastIndex = 0;
+
+  // Build regex pattern from template
+  let match: RegExpExecArray | null;
+  while ((match = variableRegex.exec(template)) !== null) {
+    // Add literal part before this match
+    if (match.index > lastIndex) {
+      const literal = template.substring(lastIndex, match.index);
+      parts.push({
+        type: "literal",
+        value: literal.replace(/[.+?^${}()[\]|\\]/g, "\\$&"), // Escape special regex chars
+      });
+    }
+
+    const operator = match[1]; // e.g., '+', '#', '.', '/', '?', '&'
+    const varNames = match[2].split(","); // Handle multiple variables in one template
+
+    varNames.forEach((varName) => {
+      if (!variables.includes(varName)) {
+        variables.push(varName);
+      }
+    });
+
+    // Add regex pattern for this template variable
+    const replacement = getRegexForOperator(operator, varNames);
+    parts.push({
+      type: "pattern",
+      value: replacement,
+    });
+
+    lastIndex = match.index + match[0].length;
+  }
+
+  // Add any remaining literal part
+  if (lastIndex < template.length) {
+    const literal = template.substring(lastIndex);
+    parts.push({
+      type: "literal",
+      value: literal.replace(/[.+?^${}()[\]|\\]/g, "\\$&"),
+    });
+  }
+
+  const regexPattern = parts.map((p) => p.value).join("");
+  const regex = new RegExp(`^${regexPattern}$`);
+
+  return {
+    pattern: template,
+    regex,
+    variables,
+  };
+}
+
+/**
+ * Get regex pattern for RFC 6570 operator
+ */
+function getRegexForOperator(operator: string, _varNames: string[]): string {
+  // Different operators allow different characters
+  switch (operator) {
+    case "+": // Reserved characters allowed
+    case "#": // Fragment (reserved chars allowed)
+      return `([a-zA-Z0-9\\-_.~:/?#[\\]@!$&'()*+,;=]*)`;
+
+    case ".": // Label (dots, no slashes)
+      return `([a-zA-Z0-9\\-_~]*)`;
+
+    case "/": // Path (no leading slash in capture)
+      return `([a-zA-Z0-9\\-_~./]*)`;
+
+    case "?": // Query (unreserved + reserved)
+    case "&": // Query continuation
+      return `([a-zA-Z0-9\\-_.~:/?#[\\]@!$&'()*+,;=%]*)`;
+
+    default: // Simple expansion (unreserved chars only: A-Z a-z 0-9 - . _ ~)
+      return `([a-zA-Z0-9\\-_~.]*)`;
+  }
+}
+
+/**
+ * Match a URI against a template and extract variables
+ */
+export function matchURITemplate(uri: string, template: URITemplate): URIMatch {
+  const regexMatch = template.regex.exec(uri);
+
+  if (!regexMatch) {
+    return {matched: false, variables: {}};
+  }
+
+  const variables: Record<string, string> = {};
+  template.variables.forEach((varName, index) => {
+    variables[varName] = regexMatch[index + 1] || "";
+  });
+
+  return {matched: true, variables};
+}
+
+/**
+ * Resolve a URI template with specific variable values
+ * Example: resolveURITemplate("cache://tools/{id}", { id: "123" }) => "cache://tools/123"
+ */
+export function resolveURITemplate(template: string, variables: Record<string, string>): string {
+  let resolved = template;
+  const variableRegex = /\{([+#./?&]?)([a-zA-Z_][a-zA-Z0-9_]*)\}/g;
+
+  let match: RegExpExecArray | null;
+  while ((match = variableRegex.exec(template)) !== null) {
+    const operator = match[1];
+    const varName = match[2];
+    const value = variables[varName] || "";
+
+    // Build the replacement based on operator
+    let replacement = "";
+    switch (operator) {
+      case "+":
+        replacement = value; // Reserved chars allowed, no prefix
+        break;
+      case "#":
+        replacement = value ? `#${value}` : "";
+        break;
+      case ".":
+        replacement = value ? `.${value}` : "";
+        break;
+      case "/":
+        replacement = value ? `/${value}` : "";
+        break;
+      case "?":
+        replacement = value ? `?${varName}=${value}` : "";
+        break;
+      case "&":
+        replacement = value ? `&${varName}=${value}` : "";
+        break;
+      default:
+        replacement = value; // Simple expansion
+    }
+
+    resolved = resolved.replace(match[0], replacement);
+  }
+
+  return resolved;
+}
+
+/**
+ * Template Registry for matching dynamic resources
+ */
+export class TemplateRegistry {
+  private templates: Map<string, URITemplate> = new Map();
+
+  /**
+   * Register a URI template pattern
+   */
+  registerTemplate(pattern: string): void {
+    if (!this.templates.has(pattern)) {
+      this.templates.set(pattern, parseURITemplate(pattern));
+    }
+  }
+
+  /**
+   * Find matching template for a given URI
+   */
+  findMatchingTemplate(uri: string): {pattern: string; match: URIMatch} | null {
+    for (const [pattern, template] of this.templates) {
+      const match = matchURITemplate(uri, template);
+      if (match.matched) {
+        return {pattern, match};
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Get all registered templates
+   */
+  getTemplates(): string[] {
+    return Array.from(this.templates.keys());
+  }
+}