agileflow 3.4.3 → 4.0.0-alpha.2

package/scripts/lib/tool-registry.yaml

@@ -1,241 +0,0 @@
-# Tool Shed Registry - MCP Tool Definitions
-#
-# Central registry of MCP tools and their capabilities.
-# Used by tool-shed.js to recommend relevant tools per task.
-#
-# Format:
-#   - name: Tool name as exposed by MCP server
-#     server: MCP server name
-#     category: Grouping category
-#     description: What the tool does
-#     keywords: Search terms for matching tasks to tools
-#     cost: token cost estimate (low/medium/high)
-#     requires_auth: Whether the tool needs credentials
-
-# =============================================================================
-# GitHub Tools (via @anthropic/mcp-server-github or similar)
-# =============================================================================
-github:
-  - name: create_issue
-    description: Create a new GitHub issue
-    keywords: [issue, bug, feature request, ticket, report]
-    cost: low
-    requires_auth: true
-
-  - name: list_issues
-    description: List and search GitHub issues
-    keywords: [issues, bugs, search, filter, backlog]
-    cost: low
-    requires_auth: true
-
-  - name: create_pull_request
-    description: Create a pull request
-    keywords: [pr, pull request, merge, review, code review]
-    cost: low
-    requires_auth: true
-
-  - name: get_pull_request
-    description: Get pull request details and diff
-    keywords: [pr, pull request, diff, changes, review]
-    cost: medium
-    requires_auth: true
-
-  - name: list_pull_requests
-    description: List pull requests with filters
-    keywords: [prs, pull requests, open, merged, review]
-    cost: low
-    requires_auth: true
-
-  - name: create_branch
-    description: Create a new git branch
-    keywords: [branch, feature branch, git]
-    cost: low
-    requires_auth: true
-
-  - name: search_code
-    description: Search code across repositories
-    keywords: [search, find, code, grep, pattern]
-    cost: medium
-    requires_auth: true
-
-  - name: get_file_contents
-    description: Get file contents from a repository
-    keywords: [read, file, contents, source]
-    cost: low
-    requires_auth: true
-
-# =============================================================================
-# Filesystem Tools (via @anthropic/mcp-server-filesystem)
-# =============================================================================
-filesystem:
-  - name: read_file
-    description: Read contents of a file
-    keywords: [read, file, contents, view]
-    cost: low
-    requires_auth: false
-
-  - name: write_file
-    description: Write contents to a file
-    keywords: [write, file, create, save]
-    cost: low
-    requires_auth: false
-
-  - name: list_directory
-    description: List directory contents
-    keywords: [list, directory, files, ls, find]
-    cost: low
-    requires_auth: false
-
-  - name: search_files
-    description: Search for files by name pattern
-    keywords: [search, find, glob, pattern, files]
-    cost: low
-    requires_auth: false
-
-# =============================================================================
-# Database Tools (via various MCP servers)
-# =============================================================================
-database:
-  - name: query
-    description: Execute a SQL query
-    keywords: [sql, query, select, database, table, join]
-    cost: medium
-    requires_auth: true
-
-  - name: list_tables
-    description: List database tables
-    keywords: [tables, schema, database, structure]
-    cost: low
-    requires_auth: true
-
-  - name: describe_table
-    description: Get table schema and columns
-    keywords: [schema, columns, table, types, structure]
-    cost: low
-    requires_auth: true
-
-# =============================================================================
-# Browser / Web Tools
-# =============================================================================
-browser:
-  - name: navigate
-    description: Navigate browser to a URL
-    keywords: [browse, navigate, url, page, website]
-    cost: medium
-    requires_auth: false
-
-  - name: screenshot
-    description: Take a screenshot of the current page
-    keywords: [screenshot, capture, visual, image, qa]
-    cost: medium
-    requires_auth: false
-
-  - name: click
-    description: Click an element on the page
-    keywords: [click, interact, button, link]
-    cost: low
-    requires_auth: false
-
-  - name: fill
-    description: Fill in a form field
-    keywords: [fill, input, form, type, text]
-    cost: low
-    requires_auth: false
-
-# =============================================================================
-# Slack / Communication Tools
-# =============================================================================
-slack:
-  - name: send_message
-    description: Send a message to a Slack channel
-    keywords: [slack, message, notify, channel, team]
-    cost: low
-    requires_auth: true
-
-  - name: search_messages
-    description: Search Slack message history
-    keywords: [slack, search, messages, history, find]
-    cost: medium
-    requires_auth: true
-
-# =============================================================================
-# Notion / Documentation Tools
-# =============================================================================
-notion:
-  - name: search
-    description: Search Notion pages and databases
-    keywords: [notion, search, wiki, docs, knowledge]
-    cost: medium
-    requires_auth: true
-
-  - name: create_page
-    description: Create a new Notion page
-    keywords: [notion, create, page, document, wiki]
-    cost: low
-    requires_auth: true
-
-  - name: update_page
-    description: Update an existing Notion page
-    keywords: [notion, update, edit, page, wiki]
-    cost: low
-    requires_auth: true
-
-# =============================================================================
-# Memory / Knowledge Tools
-# =============================================================================
-memory:
-  - name: store
-    description: Store a key-value pair in persistent memory
-    keywords: [remember, store, save, memory, persist]
-    cost: low
-    requires_auth: false
-
-  - name: retrieve
-    description: Retrieve a value from persistent memory
-    keywords: [recall, retrieve, get, memory, remember]
-    cost: low
-    requires_auth: false
-
-  - name: search_memory
-    description: Search across stored memories
-    keywords: [search, memory, find, recall]
-    cost: low
-    requires_auth: false
-
-# =============================================================================
-# Sentry / Error Tracking Tools
-# =============================================================================
-sentry:
-  - name: list_issues
-    description: List Sentry error issues
-    keywords: [errors, bugs, sentry, tracking, crashes, exceptions]
-    cost: medium
-    requires_auth: true
-
-  - name: get_issue
-    description: Get details of a specific Sentry issue
-    keywords: [error, bug, sentry, stack trace, crash]
-    cost: medium
-    requires_auth: true
-
-# =============================================================================
-# Linear / Project Management Tools
-# =============================================================================
-linear:
-  - name: create_issue
-    description: Create a Linear issue
-    keywords: [ticket, issue, task, linear, project]
-    cost: low
-    requires_auth: true
-
-  - name: list_issues
-    description: List Linear issues with filters
-    keywords: [tickets, issues, tasks, linear, backlog, sprint]
-    cost: low
-    requires_auth: true
-
-  - name: update_issue
-    description: Update a Linear issue status or details
-    keywords: [update, ticket, status, assign, linear]
-    cost: low
-    requires_auth: true

package/scripts/lib/tool-shed.js

@@ -1,441 +0,0 @@
-#!/usr/bin/env node
-/**
- * tool-shed.js - MCP Meta-Tool Registry
- *
- * Central registry for MCP tools. When agents need tools, this module
- * queries the registry by task description and returns a filtered list
- * of relevant tools, avoiding token explosion from sending all tools.
- *
- * Inspired by Stripe's "Tool Shed" pattern where a meta-tool selects
- * relevant tools per task from a large registry.
- *
- * Usage (as module):
- *   const { getToolsForTask, getAvailableServers, getToolCount } = require('./tool-shed');
- *   const tools = getToolsForTask('create a pull request for auth changes', { projectRoot });
- *
- * Usage (standalone):
- *   node scripts/lib/tool-shed.js --task "search for bugs" --project-root /path/to/project
- *   node scripts/lib/tool-shed.js --list-servers --project-root /path/to/project
- *   node scripts/lib/tool-shed.js --stats
- */
-
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-
-// Lazy-load js-yaml only when needed
-let _yaml;
-function getYaml() {
-  if (!_yaml) {
-    try {
-      _yaml = require('js-yaml');
-    } catch {
-      // Fallback: provide a minimal YAML parser for simple structures
-      _yaml = null;
-    }
-  }
-  return _yaml;
-}
-
-// =============================================================================
-// Registry Loading
-// =============================================================================
-
-/**
- * Load the built-in tool registry from YAML
- * @returns {Object} Parsed registry object keyed by server name
- */
-function loadBuiltinRegistry() {
-  const registryPath = path.join(__dirname, 'tool-registry.yaml');
-  try {
-    const content = fs.readFileSync(registryPath, 'utf8');
-    const yaml = getYaml();
-    if (yaml) {
-      return yaml.load(content) || {};
-    }
-    // Minimal fallback if js-yaml not available
-    return {};
-  } catch {
-    return {};
-  }
-}
-
-/**
- * Detect which MCP servers are configured in the project
- * @param {string} projectRoot - Project root directory
- * @returns {string[]} List of configured server names
- */
-function detectConfiguredServers(projectRoot) {
-  const servers = [];
-
-  // Check .mcp.json (Claude Code MCP config)
-  const mcpJsonPath = path.join(projectRoot, '.mcp.json');
-  if (fs.existsSync(mcpJsonPath)) {
-    try {
-      const mcpConfig = JSON.parse(fs.readFileSync(mcpJsonPath, 'utf8'));
-      if (mcpConfig.mcpServers) {
-        servers.push(...Object.keys(mcpConfig.mcpServers));
-      }
-    } catch {
-      // Ignore parse errors
-    }
-  }
-
-  // Check .claude/mcp.json (alternative location)
-  const claudeMcpPath = path.join(projectRoot, '.claude', 'mcp.json');
-  if (fs.existsSync(claudeMcpPath)) {
-    try {
-      const mcpConfig = JSON.parse(fs.readFileSync(claudeMcpPath, 'utf8'));
-      if (mcpConfig.mcpServers) {
-        servers.push(...Object.keys(mcpConfig.mcpServers));
-      }
-    } catch {
-      // Ignore parse errors
-    }
-  }
-
-  // Check agileflow-metadata.json for enabled MCP features
-  const metadataPath = path.join(projectRoot, 'docs', '00-meta', 'agileflow-metadata.json');
-  if (fs.existsSync(metadataPath)) {
-    try {
-      const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
-      const mcp =
-        metadata.agileflow && metadata.agileflow.features && metadata.agileflow.features.mcp;
-      if (mcp) {
-        for (const [server, enabled] of Object.entries(mcp)) {
-          if (enabled && !servers.includes(server)) {
-            servers.push(server);
-          }
-        }
-      }
-    } catch {
-      // Ignore parse errors
-    }
-  }
-
-  return [...new Set(servers)];
-}
-
-// =============================================================================
-// Tool Matching
-// =============================================================================
-
-/**
- * Tokenize a task description into searchable terms
- * @param {string} text - Text to tokenize
- * @returns {string[]} Lowercased tokens
- */
-function tokenize(text) {
-  if (!text) return [];
-  return text
-    .toLowerCase()
-    .replace(/[^a-z0-9\s-]/g, ' ')
-    .split(/\s+/)
-    .filter(t => t.length > 1);
-}
-
-/**
- * Score a tool's relevance to a task description
- * @param {Object} tool - Tool definition from registry
- * @param {string[]} taskTokens - Tokenized task description
- * @returns {number} Relevance score (0-100)
- */
-function scoreToolRelevance(tool, taskTokens) {
-  if (!tool.keywords || !Array.isArray(tool.keywords)) return 0;
-  if (taskTokens.length === 0) return 0;
-
-  let matchCount = 0;
-  const toolKeywords = tool.keywords.map(k => k.toLowerCase());
-
-  for (const token of taskTokens) {
-    for (const keyword of toolKeywords) {
-      // Exact match or substring match
-      if (keyword === token || keyword.includes(token) || token.includes(keyword)) {
-        matchCount++;
-        break;
-      }
-    }
-  }
-
-  if (matchCount === 0) return 0;
-
-  // Score based on how many task tokens matched tool keywords
-  const coverage = matchCount / taskTokens.length;
-  // Bonus for tools where many keywords matched
-  const density = matchCount / toolKeywords.length;
-
-  return Math.round(coverage * 60 + density * 40);
-}
-
-// =============================================================================
-// Public API
-// =============================================================================
-
-/**
- * Get tools relevant to a task description.
- * Filters by configured MCP servers and scores by keyword relevance.
- *
- * @param {string} taskDescription - Natural language task description
- * @param {Object} [options] - Options
- * @param {string} [options.projectRoot] - Project root directory
- * @param {number} [options.minScore] - Minimum relevance score (default: 15)
- * @param {number} [options.maxResults] - Maximum tools to return (default: 10)
- * @param {boolean} [options.includeUnconfigured] - Include tools from unconfigured servers (default: false)
- * @returns {Object} Results with matched tools and metadata
- */
-function getToolsForTask(taskDescription, options = {}) {
-  const {
-    projectRoot = process.cwd(),
-    minScore = 15,
-    maxResults = 10,
-    includeUnconfigured = false,
-  } = options;
-
-  const registry = loadBuiltinRegistry();
-  const configuredServers = detectConfiguredServers(projectRoot);
-  const taskTokens = tokenize(taskDescription);
-
-  const scoredTools = [];
-
-  for (const [serverName, tools] of Object.entries(registry)) {
-    if (!Array.isArray(tools)) continue;
-
-    const isConfigured = configuredServers.some(
-      s =>
-        s.toLowerCase().includes(serverName.toLowerCase()) ||
-        serverName.toLowerCase().includes(s.toLowerCase())
-    );
-
-    if (!isConfigured && !includeUnconfigured) continue;
-
-    for (const tool of tools) {
-      const score = scoreToolRelevance(tool, taskTokens);
-      if (score >= minScore) {
-        scoredTools.push({
-          ...tool,
-          server: serverName,
-          score,
-          configured: isConfigured,
-        });
-      }
-    }
-  }
-
-  // Sort by score descending, then by configured status
-  scoredTools.sort((a, b) => {
-    if (a.configured !== b.configured) return a.configured ? -1 : 1;
-    return b.score - a.score;
-  });
-
-  const results = scoredTools.slice(0, maxResults);
-
-  return {
-    task: taskDescription,
-    configured_servers: configuredServers,
-    total_matched: scoredTools.length,
-    tools: results,
-    suggestions:
-      !includeUnconfigured && scoredTools.length === 0
-        ? getUnconfiguredSuggestions(taskDescription, registry, configuredServers)
-        : [],
-  };
-}
-
-/**
- * Get suggestions for unconfigured servers that could help with a task
- * @param {string} taskDescription - Task description
- * @param {Object} registry - Full registry
- * @param {string[]} configuredServers - Already configured servers
- * @returns {Object[]} Suggested servers to configure
- */
-function getUnconfiguredSuggestions(taskDescription, registry, configuredServers) {
-  const taskTokens = tokenize(taskDescription);
-  const suggestions = [];
-
-  for (const [serverName, tools] of Object.entries(registry)) {
-    if (!Array.isArray(tools)) continue;
-
-    const isConfigured = configuredServers.some(s =>
-      s.toLowerCase().includes(serverName.toLowerCase())
-    );
-    if (isConfigured) continue;
-
-    let bestScore = 0;
-    let bestTool = null;
-    for (const tool of tools) {
-      const score = scoreToolRelevance(tool, taskTokens);
-      if (score > bestScore) {
-        bestScore = score;
-        bestTool = tool;
-      }
-    }
-
-    if (bestScore >= 20 && bestTool) {
-      suggestions.push({
-        server: serverName,
-        best_match: bestTool.name,
-        score: bestScore,
-        description: `Configure ${serverName} MCP server to use ${bestTool.name} (${bestTool.description})`,
-      });
-    }
-  }
-
-  return suggestions.sort((a, b) => b.score - a.score).slice(0, 3);
-}
-
-/**
- * Get list of available MCP servers (both configured and in registry)
- * @param {string} [projectRoot] - Project root directory
- * @returns {Object} Server listing
- */
-function getAvailableServers(projectRoot = process.cwd()) {
-  const registry = loadBuiltinRegistry();
-  const configuredServers = detectConfiguredServers(projectRoot);
-
-  const servers = {};
-  for (const [name, tools] of Object.entries(registry)) {
-    if (!Array.isArray(tools)) continue;
-    servers[name] = {
-      tool_count: tools.length,
-      configured: configuredServers.some(
-        s =>
-          s.toLowerCase().includes(name.toLowerCase()) ||
-          name.toLowerCase().includes(s.toLowerCase())
-      ),
-      tools: tools.map(t => t.name),
-    };
-  }
-
-  return {
-    configured: configuredServers,
-    registry: servers,
-    total_servers: Object.keys(servers).length,
-    total_tools: Object.values(servers).reduce((sum, s) => sum + s.tool_count, 0),
-  };
-}
-
-/**
- * Get tool count statistics
- * @returns {Object} Statistics
- */
-function getToolCount() {
-  const registry = loadBuiltinRegistry();
-  let total = 0;
-  const byServer = {};
-
-  for (const [name, tools] of Object.entries(registry)) {
-    if (!Array.isArray(tools)) continue;
-    byServer[name] = tools.length;
-    total += tools.length;
-  }
-
-  return { total, byServer };
-}
-
-/**
- * Format tool results for display
- * @param {Object} result - Result from getToolsForTask
- * @returns {string} Formatted display text
- */
-function formatToolResults(result) {
-  const lines = [];
-
-  lines.push(`## Tool Shed Results for: "${result.task}"`);
-  lines.push('');
-
-  if (result.configured_servers.length > 0) {
-    lines.push(`**Configured MCP servers**: ${result.configured_servers.join(', ')}`);
-  } else {
-    lines.push('**No MCP servers configured.** Tools are recommended based on registry only.');
-  }
-  lines.push('');
-
-  if (result.tools.length === 0) {
-    lines.push('No matching tools found.');
-    lines.push('');
-  } else {
-    lines.push(
-      `### Matched Tools (${result.total_matched} total, showing top ${result.tools.length})`
-    );
-    lines.push('');
-
-    for (const tool of result.tools) {
-      const status = tool.configured ? '✅' : '⚠️';
-      lines.push(`- ${status} **${tool.server}/${tool.name}** (score: ${tool.score})`);
-      lines.push(`  ${tool.description}`);
-      if (!tool.configured) {
-        lines.push(`  _Server not configured - add ${tool.server} to .mcp.json_`);
-      }
-    }
-    lines.push('');
-  }
-
-  if (result.suggestions.length > 0) {
-    lines.push('### Suggested Servers to Configure');
-    lines.push('');
-    for (const suggestion of result.suggestions) {
-      lines.push(`- **${suggestion.server}** - ${suggestion.description}`);
-    }
-    lines.push('');
-  }
-
-  return lines.join('\n');
-}
-
-// =============================================================================
-// CLI
-// =============================================================================
-
-if (require.main === module) {
-  const args = process.argv.slice(2);
-  const projectRoot = getArg(args, '--project-root') || process.cwd();
-
-  if (args.includes('--list-servers')) {
-    const servers = getAvailableServers(projectRoot);
-    console.log(JSON.stringify(servers, null, 2));
-  } else if (args.includes('--stats')) {
-    const stats = getToolCount();
-    console.log(JSON.stringify(stats, null, 2));
-  } else {
-    const task = getArg(args, '--task');
-    if (!task) {
-      console.error('Usage: node tool-shed.js --task "description" [--project-root /path]');
-      console.error('       node tool-shed.js --list-servers [--project-root /path]');
-      console.error('       node tool-shed.js --stats');
-      process.exit(1);
-    }
-
-    const result = getToolsForTask(task, {
-      projectRoot,
-      includeUnconfigured: args.includes('--include-unconfigured'),
-    });
-
-    if (args.includes('--json')) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.log(formatToolResults(result));
-    }
-  }
-}
-
-function getArg(args, flag) {
-  const idx = args.indexOf(flag);
-  if (idx === -1 || idx + 1 >= args.length) return null;
-  return args[idx + 1];
-}
-
-// =============================================================================
-// Exports
-// =============================================================================
-
-module.exports = {
-  loadBuiltinRegistry,
-  detectConfiguredServers,
-  tokenize,
-  scoreToolRelevance,
-  getToolsForTask,
-  getAvailableServers,
-  getToolCount,
-  formatToolResults,
-};