@axiom-lattice/protocols 2.1.9 → 2.1.11

package/src/McpLatticeProtocol.ts

@@ -0,0 +1,260 @@
+/**
+ * McpLatticeProtocol
+ *
+ * Model Context Protocol (MCP) lattice protocol for integrating MCP servers
+ * with the Lattice framework. Provides standardized interfaces for MCP
+ * client connections, tool discovery, and remote execution.
+ */
+
+import { BaseLatticeProtocol, LatticeMessage } from "./BaseLatticeProtocol";
+
+/**
+ * MCP transport type
+ */
+export type McpTransportType = "stdio" | "streamable_http" | "sse";
+
+/**
+ * MCP server configuration
+ */
+export interface McpServerConfig {
+  /** Server name */
+  name: string;
+  /** Server version */
+  version: string;
+  /** Transport type */
+  transport: McpTransportType;
+  /** Command for stdio transport (e.g., "npx", "python") */
+  command?: string;
+  /** Arguments for stdio transport */
+  args?: string[];
+  /** URL for HTTP/SSE transport */
+  url?: string;
+  /** Environment variables */
+  env?: Record<string, string>;
+  /** Connection timeout in milliseconds */
+  timeout?: number;
+  /** Retry attempts on connection failure */
+  retryAttempts?: number;
+}
+
+/**
+ * MCP tool definition
+ */
+export interface McpTool {
+  /** Tool name */
+  name: string;
+  /** Tool description */
+  description: string;
+  /** Input schema */
+  inputSchema: {
+    type: "object";
+    properties: Record<string, any>;
+    required?: string[];
+  };
+  /** Tool metadata */
+  metadata?: Record<string, any>;
+}
+
+/**
+ * MCP tool call result
+ */
+export interface McpToolResult {
+  /** Whether the call was successful */
+  success: boolean;
+  /** Result content */
+  content: Array<{
+    type: "text" | "image" | "audio" | "resource";
+    data: any;
+    mimeType?: string;
+  }>;
+  /** Error message if failed */
+  error?: string;
+  /** Execution metadata */
+  metadata?: {
+    duration: number;
+    tokens?: number;
+    model?: string;
+  };
+}
+
+/**
+ * MCP client interface
+ */
+export interface McpClient {
+  /** Client name */
+  name: string;
+  /** Client version */
+  version: string;
+  /** Server configuration */
+  serverConfig: McpServerConfig;
+  
+  /**
+   * Connect to MCP server
+   */
+  connect(): Promise<void>;
+  
+  /**
+   * Disconnect from MCP server
+   */
+  disconnect(): Promise<void>;
+  
+  /**
+   * Check if connected
+   */
+  isConnected(): boolean;
+  
+  /**
+   * List available tools
+   */
+  listTools(): Promise<McpTool[]>;
+  
+  /**
+   * Call a tool
+   */
+  callTool(name: string, arguments_: Record<string, any>): Promise<McpToolResult>;
+  
+  /**
+   * Subscribe to server notifications
+   */
+  subscribe(topic: string, handler: (data: any) => void): void;
+  
+  /**
+   * Unsubscribe from server notifications
+   */
+  unsubscribe(topic: string): void;
+  
+  /**
+   * Get client statistics
+   */
+  getStats(): McpStats;
+  
+  /**
+   * Get connection status
+   */
+  getStatus(): McpConnectionStatus;
+}
+
+/**
+ * MCP client options
+ */
+export interface McpClientOptions {
+  /** Client name */
+  name: string;
+  /** Client version */
+  version: string;
+  /** Server configuration */
+  serverConfig: McpServerConfig;
+  /** Auto-connect on initialization */
+  autoConnect?: boolean;
+  /** Error handler */
+  onError?: (error: Error) => void;
+  /** Connection status handler */
+  onStatusChange?: (status: McpConnectionStatus) => void;
+}
+
+/**
+ * MCP Lattice protocol interface
+ */
+export interface McpLatticeProtocol
+  extends BaseLatticeProtocol<McpServerConfig, McpClient> {
+  /**
+   * Server configuration
+   */
+  config: McpServerConfig;
+  
+  /**
+   * MCP client instance
+   */
+  client: McpClient;
+  
+  /**
+   * Connect to MCP server
+   */
+  connect(): Promise<void>;
+  
+  /**
+   * Disconnect from MCP server
+   */
+  disconnect(): Promise<void>;
+  
+  /**
+   * Get available tools
+   */
+  getTools(): Promise<McpTool[]>;
+  
+  /**
+   * Execute a tool
+   */
+  executeTool(
+    name: string,
+    arguments_: Record<string, any>
+  ): Promise<McpToolResult>;
+  
+  /**
+   * Execute with automatic retries
+   */
+  executeToolWithRetry(
+    name: string,
+    arguments_: Record<string, any>,
+    maxRetries?: number
+  ): Promise<McpToolResult>;
+  
+  /**
+   * Get protocol version
+   */
+  getProtocolVersion(): string;
+  
+  /**
+   * Health check
+   */
+  healthCheck(): Promise<boolean>;
+}
+
+/**
+ * MCP message types
+ */
+export enum McpMessageType {
+  CONNECT = "mcp:connect",
+  DISCONNECT = "mcp:disconnect",
+  LIST_TOOLS = "mcp:list_tools",
+  CALL_TOOL = "mcp:call_tool",
+  TOOL_RESULT = "mcp:tool_result",
+  NOTIFICATION = "mcp:notification",
+  ERROR = "mcp:error",
+  HEALTH_CHECK = "mcp:health_check",
+}
+
+/**
+ * MCP Lattice message
+ */
+export interface McpLatticeMessage extends LatticeMessage {
+  type: McpMessageType;
+  payload: {
+    toolName?: string;
+    arguments?: Record<string, any>;
+    result?: McpToolResult;
+    tools?: McpTool[];
+    error?: string;
+  };
+}
+
+/**
+ * MCP connection status
+ */
+export type McpConnectionStatus =
+  | "disconnected"
+  | "connecting"
+  | "connected"
+  | "reconnecting"
+  | "error";
+
+/**
+ * MCP statistics
+ */
+export interface McpStats {
+  totalCalls: number;
+  successfulCalls: number;
+  failedCalls: number;
+  averageLatency: number;
+  lastCallTimestamp: number;
+}

package/src/SkillLatticeProtocol.ts

@@ -0,0 +1,66 @@
+/**
+ * SkillLatticeProtocol
+ *
+ * Skill Lattice protocol for defining reusable skill components
+ */
+
+import { BaseLatticeProtocol } from "./BaseLatticeProtocol";
+import { SkillStore } from "./SkillStoreProtocol";
+
+/**
+ * Skill configuration interface
+ */
+export interface SkillConfig {
+  /** Skill name (required) */
+  name: string;
+  /** Skill description (required) */
+  description: string;
+  /** License information (optional) */
+  license?: string;
+  /** Compatibility information (optional) */
+  compatibility?: string;
+  /** Additional metadata as string-to-string map (optional) */
+  metadata?: Record<string, string>;
+  /** Skill detailed content description (optional) */
+  content?: string;
+  /** Sub-skills (optional) - Array of skill names that are sub-skills of this skill */
+  subSkills?: string[];
+}
+
+/**
+ * Skill client interface
+ * Clients can optionally implement setStore to receive store access
+ * Supports both interface implementation and any type for backward compatibility
+ */
+export interface SkillClient {
+  /**
+   * Optional method to set the store instance
+   * Called by SkillLatticeManager when registering a skill
+   */
+  setStore?: (store: SkillStore) => void;
+  
+  /**
+   * Optional store property
+   * Can be set directly or via setStore method
+   */
+  store?: SkillStore;
+  
+  /**
+   * Additional client-specific properties and methods
+   */
+  [key: string]: any;
+}
+
+/**
+ * Skill client type (supports both interface and any for backward compatibility)
+ */
+export type SkillClientType = SkillClient | any;
+
+/**
+ * Skill Lattice protocol interface
+ */
+export interface SkillLatticeProtocol
+  extends BaseLatticeProtocol<SkillConfig, SkillClientType> {
+  // Skill execution function
+  execute?: (input: any, config?: any) => Promise<any>;
+}

package/src/SkillStoreProtocol.ts

@@ -0,0 +1,193 @@
+/**
+ * SkillStoreProtocol
+ *
+ * Skill store protocol definitions for the Axiom Lattice framework
+ * Provides standardized interfaces for skill management across all implementations
+ */
+
+import { SkillConfig } from "./SkillLatticeProtocol";
+
+/**
+ * Skill type definition
+ */
+export interface Skill {
+  /**
+   * Skill identifier (key)
+   */
+  id: string;
+
+  /**
+   * Skill name
+   */
+  name: string;
+
+  /**
+   * Skill description
+   */
+  description: string;
+
+  /**
+   * License information (optional)
+   */
+  license?: string;
+
+  /**
+   * Compatibility information (optional)
+   */
+  compatibility?: string;
+
+  /**
+   * Additional metadata as string-to-string map (optional)
+   */
+  metadata?: Record<string, string>;
+
+  /**
+   * Skill detailed content description (optional)
+   * This is the markdown body content after the frontmatter
+   */
+  content?: string;
+
+  /**
+   * Sub-skills (optional)
+   * Array of skill names that are sub-skills of this skill
+   * Creates a hierarchical tree structure for organizing skills
+   */
+  subSkills?: string[];
+
+  /**
+   * Skill creation timestamp
+   */
+  createdAt: Date;
+
+  /**
+   * Skill last update timestamp
+   */
+  updatedAt: Date;
+}
+
+/**
+ * Create skill request type
+ */
+export interface CreateSkillRequest {
+  /**
+   * Skill name
+   */
+  name: string;
+
+  /**
+   * Skill description
+   */
+  description: string;
+
+  /**
+   * License information (optional)
+   */
+  license?: string;
+
+  /**
+   * Compatibility information (optional)
+   */
+  compatibility?: string;
+
+  /**
+   * Additional metadata as string-to-string map (optional)
+   */
+  metadata?: Record<string, string>;
+
+  /**
+   * Skill detailed content description (optional)
+   * This is the markdown body content after the frontmatter
+   */
+  content?: string;
+
+  /**
+   * Sub-skills (optional)
+   * Array of skill names that are sub-skills of this skill
+   * Creates a hierarchical tree structure for organizing skills
+   */
+  subSkills?: string[];
+}
+
+/**
+ * SkillStore interface
+ * Provides CRUD operations for skill data
+ */
+export interface SkillStore {
+  /**
+   * Get all skills
+   * @returns Array of all skills
+   */
+  getAllSkills(): Promise<Skill[]>;
+
+  /**
+   * Get skill by ID
+   * @param id Skill identifier
+   * @returns Skill if found, null otherwise
+   */
+  getSkillById(id: string): Promise<Skill | null>;
+
+  /**
+   * Create a new skill
+   * @param id Skill identifier
+   * @param data Skill creation data
+   * @returns Created skill
+   */
+  createSkill(id: string, data: CreateSkillRequest): Promise<Skill>;
+
+  /**
+   * Update an existing skill
+   * @param id Skill identifier
+   * @param updates Partial skill data to update
+   * @returns Updated skill if found, null otherwise
+   */
+  updateSkill(
+    id: string,
+    updates: Partial<CreateSkillRequest>
+  ): Promise<Skill | null>;
+
+  /**
+   * Delete a skill by ID
+   * @param id Skill identifier
+   * @returns true if deleted, false otherwise
+   */
+  deleteSkill(id: string): Promise<boolean>;
+
+  /**
+   * Check if skill exists
+   * @param id Skill identifier
+   * @returns true if skill exists, false otherwise
+   */
+  hasSkill(id: string): Promise<boolean>;
+
+  /**
+   * Search skills by metadata
+   * @param metadataKey Metadata key to search for
+   * @param metadataValue Metadata value to match
+   * @returns Array of matching skills
+   */
+  searchByMetadata(
+    metadataKey: string,
+    metadataValue: string
+  ): Promise<Skill[]>;
+
+  /**
+   * Filter skills by compatibility
+   * @param compatibility Compatibility string to filter by
+   * @returns Array of matching skills
+   */
+  filterByCompatibility(compatibility: string): Promise<Skill[]>;
+
+  /**
+   * Filter skills by license
+   * @param license License string to filter by
+   * @returns Array of matching skills
+   */
+  filterByLicense(license: string): Promise<Skill[]>;
+
+  /**
+   * Get sub-skills of a parent skill
+   * @param parentSkillName Parent skill name
+   * @returns Array of sub-skills if found, empty array otherwise
+   */
+  getSubSkills(parentSkillName: string): Promise<Skill[]>;
+}

package/src/index.ts

@@ -18,6 +18,9 @@ export * from "./LoggerLatticeProtocol";
 export * from "./MessageProtocol";
 export * from "./ThreadStoreProtocol";
 export * from "./AssistantStoreProtocol";
+export * from "./SkillLatticeProtocol";
+export * from "./SkillStoreProtocol";
+export * from "./McpLatticeProtocol";
 
 // 导出通用类型
 export * from "./types";