opalserve 0.1.0

package/src/cli/discover.ts

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+
+import chalk from 'chalk';
+import ora from 'ora';
+import inquirer from 'inquirer';
+
+const DEFAULT_REGISTRY_URL = 'http://localhost:3000';
+
+interface Tool {
+  id: string;
+  name: string;
+  description: string;
+  serverName: string;
+  tags: string[];
+  capabilities: string[];
+  inputSchema: Record<string, unknown>;
+}
+
+interface Server {
+  id: string;
+  name: string;
+  type: string;
+  status: string;
+  health: {
+    status: string;
+    lastChecked: string;
+  };
+}
+
+interface DiscoveryResult {
+  tools: Array<{
+    tool: Tool;
+    relevanceScore: number;
+    matchReasons: string[];
+    tokenEstimate: number;
+  }>;
+  servers: Server[];
+  totalMatches: number;
+  contextUsed: number;
+  contextBudget: number;
+  suggestions: string[];
+  queryInterpretation: string;
+}
+
+async function httpGet<T>(url: string, timeout = 10000): Promise<T> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+  
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    clearTimeout(timeoutId);
+    
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+    
+    return response.json() as Promise<T>;
+  } catch (error) {
+    clearTimeout(timeoutId);
+    if (error instanceof Error) {
+      if (error.name === 'AbortError') {
+        throw new Error('Request timeout');
+      }
+      throw error;
+    }
+    throw error;
+  }
+}
+
+async function discover(query: string, options: { registryUrl?: string; limit?: number; json?: boolean }): Promise<DiscoveryResult> {
+  const url = options.registryUrl || DEFAULT_REGISTRY_URL;
+  const spinner = ora('Discovering available tools...').start();
+
+  try {
+    const params = new URLSearchParams();
+    params.append('query', query);
+    if (options.limit) params.append('limit', String(options.limit));
+    const result = await httpGet<DiscoveryResult>(`${url}/api/v1/discover?${params}`);
+    spinner.succeed();
+    return result;
+  } catch (error) {
+    spinner.fail();
+    if (error instanceof Error) {
+      if (error.message.includes('ECONNREFUSED') || error.message.includes('fetch')) {
+        console.error(chalk.red(`\nError: Cannot connect to OpalServe registry at ${url}`));
+        console.log(chalk.yellow('\nMake sure the registry is running:'));
+        console.log(chalk.cyan('   opalserve start\n'));
+      } else {
+        console.error(chalk.red(`\nError: ${error.message}`));
+      }
+    }
+    throw error;
+  }
+}
+
+function formatResults(result: DiscoveryResult, json: boolean) {
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(chalk.bold('\n🔍 Query Interpretation:'));
+  console.log(`   ${result.queryInterpretation}\n`);
+
+  console.log(chalk.bold(`📊 Found ${result.totalMatches} matching tools`));
+  console.log(chalk.gray(`   Context used: ${result.contextUsed} / ${result.contextBudget} tokens\n`));
+
+  if (result.tools.length === 0) {
+    console.log(chalk.yellow('No tools matched your query. Try a different search term.'));
+    return;
+  }
+
+  console.log(chalk.bold('\n🛠️  Available Tools:\n'));
+
+  for (const { tool, relevanceScore, matchReasons } of result.tools) {
+    const scoreColor = relevanceScore > 0.7 ? 'green' : relevanceScore > 0.4 ? 'yellow' : 'gray';
+    
+    console.log(`  ${chalk[scoreColor](`[${Math.round(relevanceScore * 100)}%]`)} ${chalk.cyan(tool.name)}`);
+    console.log(`     ${tool.description}`);
+    console.log(`     ${chalk.gray('Server:')} ${chalk.white(tool.serverName)}`);
+    
+    if (tool.tags.length > 0) {
+      console.log(`     ${chalk.gray('Tags:')} ${tool.tags.map(t => chalk.magenta(t)).join(', ')}`);
+    }
+    
+    if (matchReasons.length > 0) {
+      console.log(`     ${chalk.gray('Matched:')} ${matchReasons.join(', ')}`);
+    }
+    console.log();
+  }
+
+  if (result.servers.length > 0) {
+    console.log(chalk.bold('\n🖥️  Connected Servers:\n'));
+    for (const server of result.servers) {
+      const statusColor = server.health.status === 'healthy' ? 'green' : server.health.status === 'degraded' ? 'yellow' : 'red';
+      console.log(`  ${chalk[statusColor]('●')} ${chalk.white(server.name)} (${server.type})`);
+    }
+    console.log();
+  }
+
+  if (result.suggestions.length > 0) {
+    console.log(chalk.bold('\n💡 Suggestions:'));
+    for (const suggestion of result.suggestions) {
+      console.log(`   • ${suggestion}`);
+    }
+    console.log();
+  }
+}
+
+async function interactiveMode(registryUrl: string) {
+  console.log(chalk.bold('\n🎯 OpalServe Discovery CLI - Interactive Mode\n'));
+  console.log(chalk.gray('Type your query or "exit" to quit\n'));
+
+  const { query } = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'query',
+      message: 'What would you like to do?',
+      default: 'what can I do?',
+    },
+  ]);
+
+  if (query.toLowerCase() === 'exit') {
+    return;
+  }
+
+  const result = await discover(query, { registryUrl });
+  formatResults(result, false);
+
+  await interactiveMode(registryUrl);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+${chalk.bold('OpalServe Discovery CLI')}
+
+${chalk.underline('Usage:')}
+  opalserve-discover [query] [options]
+
+${chalk.underline('Options:')}
+  --url <url>      Registry URL (default: http://localhost:3000)
+  --limit <n>      Maximum tools to return (default: 20)
+  --json           Output as JSON
+  --interactive    Interactive mode
+  --help, -h       Show this help
+
+${chalk.underline('Examples:')}
+  opalserve-discover "what can I do?"
+  opalserve-discover "github repository" --limit 10
+  opalserve-discover --json
+  opalserve-discover --interactive
+    `);
+    return;
+  }
+
+  const interactive = args.includes('--interactive');
+  const json = args.includes('--json');
+  
+  const urlArg = args.indexOf('--url');
+  const registryUrl = urlArg !== -1 ? args[urlArg + 1] : DEFAULT_REGISTRY_URL;
+  
+  const limitArg = args.indexOf('--limit');
+  const limit = limitArg !== -1 ? parseInt(args[limitArg + 1], 10) : 20;
+
+  if (interactive) {
+    await interactiveMode(registryUrl);
+    return;
+  }
+
+  const query = args.filter(a => !a.startsWith('--')).join(' ') || 'what can I do?';
+
+  try {
+    const result = await discover(query, { registryUrl, limit, json });
+    formatResults(result, json);
+  } catch {
+    process.exit(1);
+  }
+}
+
+main().catch(console.error);

package/src/cli/index.ts

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+import { RegistryServer } from '../registry/server.js';
+import { RegistryConfig } from '../types/index.js';
+import 'dotenv/config';
+
+const config: RegistryConfig = {
+  port: parseInt(process.env.PORT || '3000', 10),
+  host: process.env.HOST || 'localhost',
+  jwtSecret: process.env.JWT_SECRET || 'dev-secret-change-in-production',
+  apiKey: process.env.API_KEY,
+  maxToolsPerResponse: parseInt(process.env.MAX_TOOLS_PER_RESPONSE || '50', 10),
+  contextTokenBudget: parseInt(process.env.CONTEXT_TOKEN_BUDGET || '128000', 10),
+  enableAuth: process.env.ENABLE_AUTH === 'true',
+};
+
+const server = new RegistryServer(config);
+
+process.on('SIGINT', async () => {
+  await server.stop();
+  process.exit(0);
+});
+
+process.on('SIGTERM', async () => {
+  await server.stop();
+  process.exit(0);
+});
+
+console.log(`
+╔══════════════════════════════════════════════════════════════╗
+║                       O P A L S E R V E                   ║
+║          MCP Tool Registry & Discovery Hub                 ║
+║                   Enterprise Edition                        ║
+╚══════════════════════════════════════════════════════════════╝
+`);
+
+server.start().catch((error) => {
+  console.error('Failed to start server:', error);
+  process.exit(1);
+});

package/src/connectors/base.ts

@@ -0,0 +1,75 @@
+import type { MCPServer, Tool, ConnectorConfig } from '../types/index.js';
+
+export abstract class BaseConnector implements MCPServer {
+  abstract id: string;
+  abstract name: string;
+  abstract type: string;
+  protected config: ConnectorConfig;
+  protected connected: boolean = false;
+  tools: Tool[] = [];
+
+  constructor(config: ConnectorConfig) {
+    this.config = config;
+  }
+
+  abstract connect(): Promise<void>;
+  abstract disconnect(): Promise<void>;
+  abstract healthCheck(): Promise<{ healthy: boolean; latencyMs?: number }>;
+  abstract refreshTools(): Promise<Tool[]>;
+
+  getTools(): Tool[] {
+    return this.tools;
+  }
+
+  isConnected(): boolean {
+    return this.connected;
+  }
+
+  protected createTool(partial: {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    tags?: string[];
+    capabilities?: string[];
+    authRequirements?: { required?: string[]; optional?: string[] };
+    contextRequirements?: { minTokens?: number; maxTokens?: number };
+    metadata?: Record<string, unknown>;
+  }): Tool {
+    const now = new Date().toISOString();
+    return {
+      id: `${this.id}:${partial.name}`,
+      serverId: this.id,
+      serverName: this.name,
+      createdAt: now,
+      updatedAt: now,
+      name: partial.name,
+      description: partial.description,
+      inputSchema: partial.inputSchema,
+      tags: partial.tags || [],
+      capabilities: partial.capabilities || [],
+      authRequirements: {
+        required: partial.authRequirements?.required || [],
+        optional: partial.authRequirements?.optional || [],
+      },
+      contextRequirements: {
+        minTokens: partial.contextRequirements?.minTokens || 0,
+        maxTokens: partial.contextRequirements?.maxTokens || 1000,
+      },
+      metadata: partial.metadata || {},
+    };
+  }
+
+  protected async measureLatency<T>(fn: () => Promise<T>): Promise<{ result: T; latencyMs: number }> {
+    const start = performance.now();
+    const result = await fn();
+    const latencyMs = Math.round(performance.now() - start);
+    return { result, latencyMs };
+  }
+}
+
+export interface Connector {
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+  healthCheck(): Promise<{ healthy: boolean; latencyMs?: number }>;
+  getTools(): Tool[];
+}

package/src/connectors/custom.ts

@@ -0,0 +1,139 @@
+import { BaseConnector } from './base.js';
+import { ConnectorConfig, Tool, ToolDefinition } from '../types/index.js';
+
+const CUSTOM_TOOL_DEFS: ToolDefinition[] = [
+  {
+    name: 'custom_http_request',
+    description: 'Make HTTP requests to external APIs',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        method: { type: 'string', enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'], default: 'GET' },
+        url: { type: 'string', description: 'Request URL' },
+        headers: { type: 'object', description: 'HTTP headers' },
+        body: { type: 'object', description: 'Request body' },
+        timeout: { type: 'number', default: 30000 },
+      },
+      required: ['method', 'url'],
+    },
+    tags: ['http', 'api', 'custom', 'request'],
+    capabilities: ['read', 'write', 'http'],
+    authRequirements: { optional: ['api_key', 'bearer_token'] },
+    contextRequirements: { minTokens: 50, maxTokens: 500 },
+  },
+  {
+    name: 'custom_webhook_trigger',
+    description: 'Trigger a webhook with custom payload',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: 'Webhook URL' },
+        event: { type: 'string', description: 'Event name' },
+        payload: { type: 'object', description: 'Event payload' },
+        secret: { type: 'string', description: 'Webhook secret for signing' },
+      },
+      required: ['url', 'event'],
+    },
+    tags: ['webhook', 'custom', 'trigger', 'events'],
+    capabilities: ['write', 'trigger'],
+    authRequirements: { optional: ['webhook_secret'] },
+    contextRequirements: { minTokens: 30, maxTokens: 300 },
+  },
+  {
+    name: 'custom_transform_data',
+    description: 'Transform and process data with custom logic',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        operation: { type: 'string', enum: ['map', 'filter', 'reduce', 'sort', 'group'] },
+        data: { type: 'array', description: 'Input data array' },
+        expression: { type: 'string', description: 'Transformation expression' },
+      },
+      required: ['operation', 'data'],
+    },
+    tags: ['transform', 'custom', 'data', 'process'],
+    capabilities: ['read', 'transform'],
+    contextRequirements: { minTokens: 50, maxTokens: 500 },
+  },
+  {
+    name: 'custom_aggregate_metrics',
+    description: 'Aggregate and summarize metrics from input data',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        data: { type: 'array', description: 'Data to aggregate' },
+        metrics: { type: 'array', items: { type: 'string' }, description: 'Metric names to calculate' },
+        groupBy: { type: 'array', items: { type: 'string' }, description: 'Fields to group by' },
+      },
+      required: ['data', 'metrics'],
+    },
+    tags: ['metrics', 'custom', 'aggregate', 'analytics'],
+    capabilities: ['read', 'analyze'],
+    contextRequirements: { minTokens: 50, maxTokens: 400 },
+  },
+  {
+    name: 'custom_send_email',
+    description: 'Send an email via configured email service',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        to: { type: 'array', items: { type: 'string' }, description: 'Recipient emails' },
+        subject: { type: 'string', description: 'Email subject' },
+        body: { type: 'string', description: 'Email body (plain text)' },
+        html: { type: 'string', description: 'Email body (HTML)' },
+        from: { type: 'string', description: 'Sender email' },
+        replyTo: { type: 'string', description: 'Reply-to email' },
+        attachments: { type: 'array', description: 'Attachment URLs' },
+      },
+      required: ['to', 'subject', 'body'],
+    },
+    tags: ['email', 'custom', 'notification', 'send'],
+    capabilities: ['write', 'notify'],
+    authRequirements: { optional: ['smtp_credentials', 'email_api_key'] },
+    contextRequirements: { minTokens: 30, maxTokens: 300 },
+  },
+];
+
+export class CustomConnector extends BaseConnector {
+  id = 'custom';
+  name = 'Custom Tools';
+  type = 'custom';
+
+  constructor(config: ConnectorConfig) {
+    super(config);
+    this.tools = this.buildTools();
+  }
+
+  async connect(): Promise<void> {
+    this.connected = true;
+  }
+
+  async disconnect(): Promise<void> {
+    this.connected = false;
+  }
+
+  async healthCheck(): Promise<{ healthy: boolean; latencyMs?: number }> {
+    return { healthy: true };
+  }
+
+  async refreshTools(): Promise<Tool[]> {
+    return this.tools;
+  }
+
+  registerCustomTool(definition: ToolDefinition): void {
+    this.tools.push(this.createTool(definition));
+  }
+
+  unregisterCustomTool(name: string): boolean {
+    const index = this.tools.findIndex(t => t.name === name);
+    if (index !== -1) {
+      this.tools.splice(index, 1);
+      return true;
+    }
+    return false;
+  }
+
+  private buildTools(): Tool[] {
+    return CUSTOM_TOOL_DEFS.map(def => this.createTool(def));
+  }
+}

package/src/connectors/github.ts

@@ -0,0 +1,195 @@
+import { BaseConnector } from './base.js';
+import { ConnectorConfig, Tool, ToolDefinition } from '../types/index.js';
+
+const GITHUB_TOOL_DEFS: ToolDefinition[] = [
+  {
+    name: 'github_search_repositories',
+    description: 'Search for GitHub repositories by query, language, stars, and other criteria',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        q: { type: 'string', description: 'Search query' },
+        language: { type: 'string', description: 'Programming language filter' },
+        sort: { type: 'string', enum: ['stars', 'forks', 'updated'] },
+      },
+      required: ['q'],
+    },
+    tags: ['search', 'repositories', 'github'],
+    capabilities: ['read', 'search'],
+    authRequirements: { required: ['github_token'] },
+    contextRequirements: { minTokens: 50, maxTokens: 500 },
+  },
+  {
+    name: 'github_get_file_contents',
+    description: 'Get the contents of a file or directory from a GitHub repository',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        owner: { type: 'string', description: 'Repository owner' },
+        repo: { type: 'string', description: 'Repository name' },
+        path: { type: 'string', description: 'Path to file or directory' },
+        branch: { type: 'string', description: 'Branch name' },
+      },
+      required: ['owner', 'repo', 'path'],
+    },
+    tags: ['files', 'repository', 'github'],
+    capabilities: ['read'],
+    authRequirements: { required: ['github_token'] },
+    contextRequirements: { minTokens: 50, maxTokens: 1000 },
+  },
+  {
+    name: 'github_list_issues',
+    description: 'List issues in a GitHub repository with filtering options',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        owner: { type: 'string', description: 'Repository owner' },
+        repo: { type: 'string', description: 'Repository name' },
+        state: { type: 'string', enum: ['open', 'closed', 'all'] },
+        labels: { type: 'array', items: { type: 'string' } },
+        sort: { type: 'string', enum: ['created', 'updated', 'comments'] },
+      },
+      required: ['owner', 'repo'],
+    },
+    tags: ['issues', 'tickets', 'github'],
+    capabilities: ['read', 'list'],
+    authRequirements: { required: ['github_token'] },
+    contextRequirements: { minTokens: 50, maxTokens: 500 },
+  },
+  {
+    name: 'github_create_issue',
+    description: 'Create a new issue in a GitHub repository',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        owner: { type: 'string', description: 'Repository owner' },
+        repo: { type: 'string', description: 'Repository name' },
+        title: { type: 'string', description: 'Issue title' },
+        body: { type: 'string', description: 'Issue body' },
+        labels: { type: 'array', items: { type: 'string' } },
+        assignees: { type: 'array', items: { type: 'string' } },
+      },
+      required: ['owner', 'repo', 'title'],
+    },
+    tags: ['issues', 'create', 'github'],
+    capabilities: ['write', 'create'],
+    authRequirements: { required: ['github_token'] },
+    contextRequirements: { minTokens: 50, maxTokens: 200 },
+  },
+  {
+    name: 'github_list_pull_requests',
+    description: 'List and filter pull requests in a GitHub repository',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        owner: { type: 'string', description: 'Repository owner' },
+        repo: { type: 'string', description: 'Repository name' },
+        state: { type: 'string', enum: ['open', 'closed', 'all'] },
+        sort: { type: 'string', enum: ['created', 'updated', 'popularity'] },
+        head: { type: 'string', description: 'Filter by head branch' },
+      },
+      required: ['owner', 'repo'],
+    },
+    tags: ['pull-requests', 'code-review', 'github'],
+    capabilities: ['read', 'list'],
+    authRequirements: { required: ['github_token'] },
+    contextRequirements: { minTokens: 50, maxTokens: 500 },
+  },
+  {
+    name: 'github_create_pull_request',
+    description: 'Create a new pull request in a GitHub repository',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        owner: { type: 'string', description: 'Repository owner' },
+        repo: { type: 'string', description: 'Repository name' },
+        title: { type: 'string', description: 'PR title' },
+        body: { type: 'string', description: 'PR body' },
+        head: { type: 'string', description: 'Head branch' },
+        base: { type: 'string', description: 'Base branch', default: 'main' },
+        draft: { type: 'boolean', description: 'Create as draft PR' },
+      },
+      required: ['owner', 'repo', 'title', 'head', 'base'],
+    },
+    tags: ['pull-requests', 'create', 'github'],
+    capabilities: ['write', 'create'],
+    authRequirements: { required: ['github_token'] },
+    contextRequirements: { minTokens: 50, maxTokens: 300 },
+  },
+  {
+    name: 'github_list_commits',
+    description: 'Get list of commits from a branch in a GitHub repository',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        owner: { type: 'string', description: 'Repository owner' },
+        repo: { type: 'string', description: 'Repository name' },
+        sha: { type: 'string', description: 'Branch or commit SHA' },
+        per_page: { type: 'number', description: 'Results per page', default: 30 },
+        page: { type: 'number', description: 'Page number', default: 1 },
+      },
+      required: ['owner', 'repo'],
+    },
+    tags: ['commits', 'history', 'github'],
+    capabilities: ['read', 'list'],
+    authRequirements: { required: ['github_token'] },
+    contextRequirements: { minTokens: 50, maxTokens: 800 },
+  },
+  {
+    name: 'github_search_code',
+    description: 'Search for code across GitHub repositories',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        q: { type: 'string', description: 'Search query with code-specific syntax' },
+        language: { type: 'string', description: 'Language filter' },
+        repo: { type: 'string', description: 'Limit search to repository' },
+      },
+      required: ['q'],
+    },
+    tags: ['search', 'code', 'github'],
+    capabilities: ['read', 'search'],
+    authRequirements: { required: ['github_token'] },
+    contextRequirements: { minTokens: 50, maxTokens: 500 },
+  },
+];
+
+export class GitHubConnector extends BaseConnector {
+  id = 'github';
+  name = 'GitHub';
+  type = 'github';
+  private token?: string;
+
+  constructor(config: ConnectorConfig) {
+    super(config);
+    this.token = config.auth?.credentials?.token;
+    this.tools = this.buildTools();
+  }
+
+  async connect(): Promise<void> {
+    this.connected = true;
+  }
+
+  async disconnect(): Promise<void> {
+    this.connected = false;
+  }
+
+  async healthCheck(): Promise<{ healthy: boolean; latencyMs?: number }> {
+    const { result, latencyMs } = await this.measureLatency(async () => {
+      if (!this.token) return true;
+      const response = await fetch('https://api.github.com/rate_limit', {
+        headers: { Authorization: `Bearer ${this.token}` },
+      });
+      return response.ok;
+    });
+    return { healthy: result, latencyMs };
+  }
+
+  async refreshTools(): Promise<Tool[]> {
+    return this.tools;
+  }
+
+  private buildTools(): Tool[] {
+    return GITHUB_TOOL_DEFS.map(def => this.createTool(def));
+  }
+}