@operor/skills 0.1.0

package/src/SkillManager.ts

@@ -0,0 +1,98 @@
+import type { Skill } from '@operor/core';
+import { MCPSkill } from './MCPSkill.js';
+import { PromptSkill } from './PromptSkill.js';
+import type { MCPSkillConfig, SkillsConfig, PromptSkillConfig } from './config.js';
+import { isPromptSkillConfig } from './config.js';
+
+export class SkillManager {
+  private skills: Skill[] = [];
+
+  async initialize(config: SkillsConfig): Promise<Skill[]> {
+    const enabledSkills = config.skills.filter(s => s.enabled !== false);
+
+    for (const skillConfig of enabledSkills) {
+      if (isPromptSkillConfig(skillConfig)) {
+        const validationError = SkillManager.validatePromptConfig(skillConfig);
+        if (validationError) {
+          console.warn(`[SkillManager] Skipping prompt skill "${skillConfig.name}": ${validationError}`);
+          continue;
+        }
+        try {
+          const skill = new PromptSkill(skillConfig);
+          await skill.initialize();
+          this.skills.push(skill);
+          console.log(`[SkillManager] ✅ ${skill.name}: prompt skill loaded`);
+        } catch (error: any) {
+          console.warn(`[SkillManager] ⚠️ Failed to load prompt skill "${skillConfig.name}": ${error.message}`);
+        }
+      } else {
+        const validationError = SkillManager.validateConfig(skillConfig);
+        if (validationError) {
+          console.warn(`[SkillManager] Skipping skill "${skillConfig.name}": ${validationError}`);
+          continue;
+        }
+        try {
+          const skill = new MCPSkill(skillConfig);
+          await skill.initialize();
+          this.skills.push(skill);
+          const toolCount = Object.keys(skill.tools).length;
+          console.log(`[SkillManager] ✅ ${skill.name}: ${toolCount} tools loaded`);
+        } catch (error: any) {
+          console.warn(`[SkillManager] ⚠️ Failed to start skill "${skillConfig.name}": ${error.message}`);
+        }
+      }
+    }
+
+    return this.skills;
+  }
+
+  async closeAll(): Promise<void> {
+    const closePromises = this.skills.map(async (skill) => {
+      try {
+        if (skill.close) await skill.close();
+      } catch (error: any) {
+        console.warn(`[SkillManager] Error closing skill "${skill.name}": ${error.message}`);
+      }
+    });
+    await Promise.all(closePromises);
+    this.skills = [];
+  }
+
+  getSkills(): Skill[] {
+    return this.skills;
+  }
+
+  getPromptSkills(): PromptSkill[] {
+    return this.skills.filter((s): s is PromptSkill => s instanceof PromptSkill);
+  }
+
+  getMCPSkills(): MCPSkill[] {
+    return this.skills.filter((s): s is MCPSkill => s instanceof MCPSkill);
+  }
+
+  static validateConfig(config: MCPSkillConfig): string | null {
+    if (!config.name || typeof config.name !== 'string') {
+      return 'Missing or invalid "name" field';
+    }
+    if (!['stdio', 'http', 'sse'].includes(config.transport)) {
+      return `Invalid transport "${config.transport}" — must be "stdio", "http", or "sse"`;
+    }
+    if (config.transport === 'stdio' && !config.command) {
+      return 'stdio transport requires a "command" field';
+    }
+    if ((config.transport === 'http' || config.transport === 'sse') && !config.url) {
+      return `${config.transport} transport requires a "url" field`;
+    }
+    return null;
+  }
+
+  static validatePromptConfig(config: PromptSkillConfig): string | null {
+    if (!config.name || typeof config.name !== 'string') {
+      return 'Missing or invalid "name" field';
+    }
+    if (!config.content || typeof config.content !== 'string' || !config.content.trim()) {
+      return 'Missing or empty "content" field';
+    }
+    return null;
+  }
+}

package/src/__tests__/MCPSkill.test.ts

@@ -0,0 +1,308 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { MCPSkill } from '../MCPSkill.js';
+import type { MCPSkillConfig } from '../config.js';
+
+// Mock @ai-sdk/mcp
+vi.mock('@ai-sdk/mcp', () => ({
+  createMCPClient: vi.fn(),
+}));
+
+// Mock @modelcontextprotocol/sdk stdio transport
+vi.mock('@modelcontextprotocol/sdk/client/stdio.js', () => {
+  return {
+    StdioClientTransport: class StdioClientTransport {
+      command: string;
+      args: string[];
+      env: any;
+      constructor(opts: any) {
+        this.command = opts.command;
+        this.args = opts.args;
+        this.env = opts.env;
+      }
+    },
+  };
+});
+
+import { createMCPClient } from '@ai-sdk/mcp';
+
+const mockCreateMCPClient = vi.mocked(createMCPClient);
+
+function makeMockClient(tools: Record<string, any> = {}) {
+  return {
+    tools: vi.fn().mockResolvedValue(tools),
+    close: vi.fn().mockResolvedValue(undefined),
+  };
+}
+
+describe('MCPSkill', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('sets name from config', () => {
+    const skill = new MCPSkill({
+      name: 'github',
+      transport: 'http',
+      url: 'http://localhost:3000/mcp',
+    });
+    expect(skill.name).toBe('github');
+  });
+
+  it('is not ready before initialize', () => {
+    const skill = new MCPSkill({
+      name: 'test',
+      transport: 'http',
+      url: 'http://localhost:3000/mcp',
+    });
+    expect(skill.isReady()).toBe(false);
+    expect(skill.tools).toEqual({});
+  });
+
+  describe('initialize', () => {
+    it('connects and discovers tools via http transport', async () => {
+      const mockTools = {
+        search: {
+          description: 'Search the web',
+          parameters: {
+            type: 'object',
+            properties: { query: { type: 'string' } },
+          },
+          execute: vi.fn().mockResolvedValue('result'),
+        },
+      };
+      mockCreateMCPClient.mockResolvedValue(makeMockClient(mockTools) as any);
+
+      const skill = new MCPSkill({
+        name: 'brave',
+        transport: 'http',
+        url: 'http://localhost:3000/mcp',
+      });
+      await skill.initialize();
+
+      expect(skill.isReady()).toBe(true);
+      expect(Object.keys(skill.tools)).toEqual(['brave__search']);
+      expect(skill.tools['brave__search'].description).toBe('Search the web');
+    });
+
+    it('uses custom toolPrefix when set', async () => {
+      const mockTools = {
+        list_repos: {
+          description: 'List repos',
+          parameters: { type: 'object', properties: {} },
+          execute: vi.fn(),
+        },
+      };
+      mockCreateMCPClient.mockResolvedValue(makeMockClient(mockTools) as any);
+
+      const skill = new MCPSkill({
+        name: 'github',
+        transport: 'http',
+        url: 'http://localhost:3000/mcp',
+        toolPrefix: 'gh',
+      });
+      await skill.initialize();
+
+      expect(Object.keys(skill.tools)).toEqual(['gh__list_repos']);
+    });
+
+    it('handles tools with jsonSchema wrapper', async () => {
+      const innerSchema = {
+        type: 'object',
+        properties: { id: { type: 'number' } },
+        required: ['id'],
+      };
+      const mockTools = {
+        get_order: {
+          description: 'Get order by ID',
+          parameters: { jsonSchema: innerSchema },
+          execute: vi.fn(),
+        },
+      };
+      mockCreateMCPClient.mockResolvedValue(makeMockClient(mockTools) as any);
+
+      const skill = new MCPSkill({
+        name: 'shop',
+        transport: 'http',
+        url: 'http://localhost:3000/mcp',
+      });
+      await skill.initialize();
+
+      expect(skill.tools['shop__get_order'].parameters).toEqual(innerSchema);
+    });
+
+    it('handles tools with inputSchema (AI SDK MCP client format)', async () => {
+      const innerSchema = {
+        type: 'object',
+        properties: { url: { type: 'string', description: 'URL to crawl' } },
+        required: ['url'],
+        additionalProperties: false,
+      };
+      const mockTools = {
+        md: {
+          description: 'Crawl a URL and return markdown',
+          inputSchema: { jsonSchema: innerSchema },
+          execute: vi.fn(),
+        },
+      };
+      mockCreateMCPClient.mockResolvedValue(makeMockClient(mockTools) as any);
+
+      const skill = new MCPSkill({
+        name: 'crawl4ai',
+        transport: 'sse',
+        url: 'http://localhost:11235/mcp/sse',
+      });
+      await skill.initialize();
+
+      expect(skill.tools['crawl4ai__md'].parameters).toEqual(innerSchema);
+    });
+
+    it('falls back to empty schema when no parameters', async () => {
+      const mockTools = {
+        ping: {
+          description: 'Ping',
+          execute: vi.fn(),
+        },
+      };
+      mockCreateMCPClient.mockResolvedValue(makeMockClient(mockTools) as any);
+
+      const skill = new MCPSkill({
+        name: 'svc',
+        transport: 'http',
+        url: 'http://localhost:3000/mcp',
+      });
+      await skill.initialize();
+
+      expect(skill.tools['svc__ping'].parameters).toEqual({
+        type: 'object',
+        properties: {},
+      });
+    });
+
+    it('executes a tool by delegating to the MCP tool', async () => {
+      const mockExecute = vi.fn().mockResolvedValue('tool-result');
+      const mockTools = {
+        do_thing: {
+          description: 'Do thing',
+          parameters: { type: 'object', properties: {} },
+          execute: mockExecute,
+        },
+      };
+      mockCreateMCPClient.mockResolvedValue(makeMockClient(mockTools) as any);
+
+      const skill = new MCPSkill({
+        name: 'test',
+        transport: 'http',
+        url: 'http://localhost:3000/mcp',
+      });
+      await skill.initialize();
+
+      const result = await skill.tools['test__do_thing'].execute!({ foo: 'bar' });
+      expect(result).toBe('tool-result');
+      expect(mockExecute).toHaveBeenCalledWith(
+        { foo: 'bar' },
+        expect.objectContaining({ toolCallId: expect.stringMatching(/^call_/) }),
+      );
+    });
+
+    it('creates stdio transport for stdio config', async () => {
+      const mockClient = makeMockClient({});
+      mockCreateMCPClient.mockResolvedValue(mockClient as any);
+
+      const skill = new MCPSkill({
+        name: 'fs',
+        transport: 'stdio',
+        command: 'node',
+        args: ['server.js'],
+      });
+      await skill.initialize();
+
+      expect(mockCreateMCPClient).toHaveBeenCalledWith({
+        transport: expect.objectContaining({ command: 'node' }),
+      });
+    });
+
+    it('creates sse transport for sse config', async () => {
+      const mockClient = makeMockClient({});
+      mockCreateMCPClient.mockResolvedValue(mockClient as any);
+
+      const skill = new MCPSkill({
+        name: 'remote',
+        transport: 'sse',
+        url: 'http://localhost:3000/sse',
+      });
+      await skill.initialize();
+
+      expect(mockCreateMCPClient).toHaveBeenCalledWith({
+        transport: { type: 'sse', url: 'http://localhost:3000/sse', headers: undefined },
+      });
+    });
+  });
+
+  describe('close', () => {
+    it('closes the client and resets ready state', async () => {
+      const mockClient = makeMockClient({});
+      mockCreateMCPClient.mockResolvedValue(mockClient as any);
+
+      const skill = new MCPSkill({
+        name: 'test',
+        transport: 'http',
+        url: 'http://localhost:3000/mcp',
+      });
+      await skill.initialize();
+      expect(skill.isReady()).toBe(true);
+
+      await skill.close();
+      expect(skill.isReady()).toBe(false);
+      expect(mockClient.close).toHaveBeenCalled();
+    });
+
+    it('handles close when not initialized', async () => {
+      const skill = new MCPSkill({
+        name: 'test',
+        transport: 'http',
+        url: 'http://localhost:3000/mcp',
+      });
+      // Should not throw
+      await skill.close();
+      expect(skill.isReady()).toBe(false);
+    });
+  });
+
+  describe('transport validation', () => {
+    it('throws for stdio without command', async () => {
+      const skill = new MCPSkill({
+        name: 'bad',
+        transport: 'stdio',
+      } as MCPSkillConfig);
+
+      await expect(skill.initialize()).rejects.toThrow('stdio transport requires a "command" field');
+    });
+
+    it('throws for http without url', async () => {
+      const skill = new MCPSkill({
+        name: 'bad',
+        transport: 'http',
+      } as MCPSkillConfig);
+
+      await expect(skill.initialize()).rejects.toThrow('http transport requires a "url" field');
+    });
+
+    it('throws for sse without url', async () => {
+      const skill = new MCPSkill({
+        name: 'bad',
+        transport: 'sse',
+      } as MCPSkillConfig);
+
+      await expect(skill.initialize()).rejects.toThrow('sse transport requires a "url" field');
+    });
+
+    it('throws for unknown transport type', async () => {
+      const skill = new MCPSkill({
+        name: 'bad',
+        transport: 'websocket' as any,
+      });
+
+      await expect(skill.initialize()).rejects.toThrow('Unknown transport type: websocket');
+    });
+  });
+});

package/src/__tests__/SkillManager.test.ts

@@ -0,0 +1,172 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { SkillManager } from '../SkillManager.js';
+import type { SkillsConfig, MCPSkillConfig } from '../config.js';
+
+// Mock MCPSkill so we don't need real MCP connections
+vi.mock('../MCPSkill.js', () => {
+  return {
+    MCPSkill: class MockMCPSkill {
+      name: string;
+      tools: Record<string, any> = {};
+      private _ready = false;
+      private _shouldFail: boolean;
+
+      constructor(config: MCPSkillConfig) {
+        this.name = config.name;
+        // Convention: name starting with "fail-" will throw on initialize
+        this._shouldFail = config.name.startsWith('fail-');
+      }
+
+      async initialize(): Promise<void> {
+        if (this._shouldFail) {
+          throw new Error(`Connection refused for ${this.name}`);
+        }
+        this._ready = true;
+        this.tools = {
+          [`${this.name}__tool1`]: {
+            name: `${this.name}__tool1`,
+            description: 'A test tool',
+            parameters: {},
+          },
+        };
+      }
+
+      isReady(): boolean {
+        return this._ready;
+      }
+
+      async close(): Promise<void> {
+        this._ready = false;
+      }
+    },
+  };
+});
+
+describe('SkillManager', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('initialize', () => {
+    it('initializes enabled skills', async () => {
+      const manager = new SkillManager();
+      const config: SkillsConfig = {
+        skills: [
+          { name: 'alpha', transport: 'http', url: 'http://localhost:3000/mcp' },
+          { name: 'beta', transport: 'http', url: 'http://localhost:3001/mcp' },
+        ],
+      };
+
+      const skills = await manager.initialize(config);
+      expect(skills).toHaveLength(2);
+      expect(skills[0].name).toBe('alpha');
+      expect(skills[1].name).toBe('beta');
+    });
+
+    it('skips disabled skills', async () => {
+      const manager = new SkillManager();
+      const config: SkillsConfig = {
+        skills: [
+          { name: 'enabled-one', transport: 'http', url: 'http://localhost/mcp' },
+          { name: 'disabled-one', transport: 'http', url: 'http://localhost/mcp', enabled: false },
+        ],
+      };
+
+      const skills = await manager.initialize(config);
+      expect(skills).toHaveLength(1);
+      expect(skills[0].name).toBe('enabled-one');
+    });
+
+    it('skips skills with invalid config', async () => {
+      const manager = new SkillManager();
+      const config: SkillsConfig = {
+        skills: [
+          { name: '', transport: 'stdio', command: 'node' }, // invalid: empty name
+          { name: 'valid', transport: 'http', url: 'http://localhost/mcp' },
+        ],
+      };
+
+      const skills = await manager.initialize(config);
+      expect(skills).toHaveLength(1);
+      expect(skills[0].name).toBe('valid');
+    });
+
+    it('skips skills that fail to start and continues', async () => {
+      const manager = new SkillManager();
+      const config: SkillsConfig = {
+        skills: [
+          { name: 'fail-broken', transport: 'http', url: 'http://localhost/mcp' },
+          { name: 'healthy', transport: 'http', url: 'http://localhost/mcp' },
+        ],
+      };
+
+      const skills = await manager.initialize(config);
+      expect(skills).toHaveLength(1);
+      expect(skills[0].name).toBe('healthy');
+    });
+
+    it('returns empty array when all skills fail', async () => {
+      const manager = new SkillManager();
+      const config: SkillsConfig = {
+        skills: [
+          { name: 'fail-one', transport: 'http', url: 'http://localhost/mcp' },
+          { name: 'fail-two', transport: 'http', url: 'http://localhost/mcp' },
+        ],
+      };
+
+      const skills = await manager.initialize(config);
+      expect(skills).toHaveLength(0);
+    });
+
+    it('returns empty array for empty config', async () => {
+      const manager = new SkillManager();
+      const skills = await manager.initialize({ skills: [] });
+      expect(skills).toHaveLength(0);
+    });
+  });
+
+  describe('getSkills', () => {
+    it('returns initialized skills', async () => {
+      const manager = new SkillManager();
+      await manager.initialize({
+        skills: [
+          { name: 'one', transport: 'http', url: 'http://localhost/mcp' },
+          { name: 'two', transport: 'http', url: 'http://localhost/mcp' },
+        ],
+      });
+
+      const skills = manager.getSkills();
+      expect(skills).toHaveLength(2);
+      expect(skills.map(s => s.name)).toEqual(['one', 'two']);
+    });
+
+    it('returns empty array before initialization', () => {
+      const manager = new SkillManager();
+      expect(manager.getSkills()).toEqual([]);
+    });
+  });
+
+  describe('closeAll', () => {
+    it('closes all skills and clears the list', async () => {
+      const manager = new SkillManager();
+      await manager.initialize({
+        skills: [
+          { name: 'a', transport: 'http', url: 'http://localhost/mcp' },
+          { name: 'b', transport: 'http', url: 'http://localhost/mcp' },
+        ],
+      });
+
+      expect(manager.getSkills()).toHaveLength(2);
+
+      await manager.closeAll();
+      expect(manager.getSkills()).toHaveLength(0);
+    });
+
+    it('handles closeAll when no skills are initialized', async () => {
+      const manager = new SkillManager();
+      // Should not throw
+      await manager.closeAll();
+      expect(manager.getSkills()).toEqual([]);
+    });
+  });
+});