Merge pull request #40 from drupaltools/39_mcp

Author: theodorosploumis

.github/workflows/build-api.yml

@@ -0,0 +1,47 @@
+name: Build API Data
+
+on:
+  push:
+    branches: [ main, master ]
+    paths:
+      - '_data/projects/**'
+      - '_scripts/build-api-data.js'
+  pull_request:
+    branches: [ main, master ]
+    paths:
+      - '_data/projects/**'
+  workflow_dispatch:
+
+jobs:
+  build-api:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '18'
+        cache: 'npm'
+
+    - name: Install dependencies
+      run: npm ci
+
+    - name: Build API data
+      run: node _scripts/build-api-data.js
+
+    - name: Commit API data
+      run: |
+        git config --local user.email "action@github.com"
+        git config --local user.name "GitHub Action"
+        git add api/data/
+        if git diff --staged --quiet; then
+          git commit -m "Auto-update API data [skip ci]"
+          git push
+        else
+          echo "No changes to commit"
+        fi

.gitignore

@@ -2,3 +2,13 @@ _site/
 .sass-cache
 .jekyll-cache
 .jekyll-metadata
+
+# Node.js
+node_modules/
+package-lock.json
+
+# Generated files (these are built, not edited)
+# Note: api/data/ is committed as it's needed for GitHub Pages
+drupaltools.log
+*.log
+.DS_Store

AUTOMATION.md

@@ -0,0 +1,107 @@
+# API Data Automation
+
+This document explains how the API data is automatically generated and kept in sync with the project YAML files.
+
+## Overview
+
+The Web API (`/api/client.html`) uses pre-built JSON data for performance and GitHub Pages compatibility. This data is automatically generated from the YAML files in `_data/projects/`.
+
+## Automation Methods
+
+### 1. Jekyll Plugin (Automatic on GitHub Pages)
+- **File**: `_plugins/api_generator.rb`
+- **When it runs**: During every Jekyll build
+- **How it works**:
+  - Reads all YAML files from `_data/projects/`
+  - Generates combined JSON (`api/data/projects.json`)
+  - Creates JavaScript module (`api/data/drupal-tools-data.js`)
+  - Creates individual JSON files for each project
+
+### 2. Git Pre-commit Hook (Local Development)
+- **File**: `.git/hooks/pre-commit`
+- **When it runs**: Before every commit
+- **What it does**:
+  - Checks if any YAML files were staged
+  - Runs `npm run build-api` if changes detected
+  - Automatically stages the generated API data
+
+### 3. GitHub Actions (CI/CD)
+- **File**: `.github/workflows/build-api.yml`
+- **When it runs**: On pushes to main/master, pull requests, or manual trigger
+- **Features**:
+  - Builds API data in isolated environment
+  - Commits generated data back to repository
+  - Ensures API is always up-to-date
+
+### 4. NPM Scripts (Manual Control)
+```bash
+# Build API data once
+npm run build-api
+
+# Watch for changes and rebuild automatically
+npm run watch-api
+
+# Build and stage before committing
+npm run precommit
+```
+
+## Data Flow
+
+```
+┌─────────────────┐
+│  _data/projects/ │
+│   *.yml files    │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐     ┌──────────────────┐
+│   Automation    │────▶│   Generated      │
+│ (Jekyll/Git/NPM) │     │   JSON Data      │
+└─────────────────┘     └──────────────────┘
+                               │
+                               ▼
+                    ┌──────────────────┐
+                    │   GitHub Pages   │
+                    │     /api/*       │
+                    └──────────────────┘
+```
+
+## File Structure After Build
+
+```
+api/
+├── data/
+│   ├── projects.json           # All projects + metadata
+│   ├── drupal-tools-data.js    # JavaScript module
+│   ├── blt.json               # Individual project data
+│   ├── acquia-desktop.json    # Individual project data
+│   └── ...                     # One JSON per project
+├── client.html                 # Web UI
+├── index.html                  # API documentation
+└── drupal-tools.js            # Client library
+```
+
+## Troubleshooting
+
+### API data is out of sync
+Run: `npm run build-api`
+
+### Pre-commit hook not working
+```bash
+chmod +x .git/hooks/pre-commit
+```
+
+### GitHub Actions failing
+Check: `.github/workflows/build-api.yml`
+
+### Local development with auto-rebuild
+```bash
+npm run watch-api
+```
+
+## Performance
+
+- Initial load: ~50KB of JSON data
+- Search: Instant (client-side)
+- No external dependencies on GitHub Pages
+- Cached by browsers for 1 hour

README.md

@@ -48,6 +48,22 @@ bundle install
 bundle exec jekyll serve --server 8080
 ```
 
+## MCP Server
+
+This repository includes an MCP (Model Context Protocol) server that provides programmatic access to the Drupal tools database. See [mcp-server/README.md](./mcp-server/README.md) for details.
+
+### Quick Start
+
+```bash
+npm install
+npm run mcp
+```
+
+The MCP server provides three tools:
+- `list_tools`: List all tools with optional category filtering
+- `search_tools`: Semantic search for tools
+- `get_tool`: Get detailed information about a specific tool
+
 Or just open in Gitpod!
 
 [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/drupaltools/drupaltools.github.io)

_plugins/api_generator.rb

@@ -0,0 +1,57 @@
+# Jekyll plugin to automatically generate API data
+# This runs during Jekyll build on GitHub Pages
+
+require 'json'
+require 'yaml'
+
+module Jekyll
+  class ApiDataGenerator < Generator
+    safe true
+    priority :low
+
+    def generate(site)
+      # Read all project YAML files
+      projects = []
+      categories = Set.new
+
+      Dir.glob('_data/projects/*.yml').each do |file|
+        data = YAML.load_file(file)
+        next unless data
+
+        id = File.basename(file, '.yml')
+        project = data.merge('id' => id)
+        projects << project
+
+        # Collect categories
+        if data['category']
+          data['category'].each { |cat| categories << cat }
+        end
+      end
+
+      # Create API data structure
+      api_data = {
+        'projects' => projects,
+        'categories' => categories.to_a.sort,
+        'total' => projects.length,
+        'updated' => Time.now.iso8601
+      }
+
+      # Write combined data file
+      File.write('api/data/projects.json', JSON.pretty_generate(api_data))
+
+      # Write JavaScript module for easy client-side access
+      js_content = "// Auto-generated Drupal Tools data\nwindow.DrupalToolsData = #{JSON.generate(api_data)};"
+      File.write('api/data/drupal-tools-data.js', js_content)
+
+      # Create individual project files
+      projects.each do |project|
+        File.write(
+          "api/data/#{project['id']}.json",
+          JSON.pretty_generate(project)
+        )
+      end
+
+      Jekyll.logger.info "API Data Generator: Generated #{projects.length} projects with #{categories.size} categories"
+    end
+  end
+end

_scripts/build-api-data.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+
+// Build script to generate JSON data for the API
+// Run this with: node _scripts/build-api-data.js
+
+import fs from 'fs/promises';
+import path from 'path';
+import yaml from 'js-yaml';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const projectsDir = path.join(__dirname, '../_data/projects');
+const outputDir = path.join(__dirname, '../api/data');
+
+async function buildApiData() {
+  try {
+    // Ensure output directory exists
+    await fs.mkdir(outputDir, { recursive: true });
+
+    const files = await fs.readdir(projectsDir);
+    const projects = [];
+    const categories = new Set();
+
+    // Process each YAML file
+    for (const file of files) {
+      if (file.endsWith('.yml') || file.endsWith('.yaml')) {
+        const filePath = path.join(projectsDir, file);
+        const content = await fs.readFile(filePath, 'utf-8');
+        const data = yaml.load(content);
+
+        const id = file.replace(/\.(yml|yaml)$/, '');
+        const project = {
+          ...data,
+          id,
+          path: filePath
+        };
+
+        projects.push(project);
+
+        // Collect categories
+        if (data.category) {
+          data.category.forEach(cat => categories.add(cat));
+        }
+      }
+    }
+
+    // Write combined data file
+    const indexData = {
+      projects,
+      categories: Array.from(categories).sort(),
+      total: projects.length,
+      updated: new Date().toISOString()
+    };
+
+    await fs.writeFile(
+      path.join(outputDir, 'projects.json'),
+      JSON.stringify(indexData, null, 2)
+    );
+
+    // Write individual project files
+    for (const project of projects) {
+      await fs.writeFile(
+        path.join(outputDir, `${project.id}.json`),
+        JSON.stringify(project, null, 2)
+      );
+    }
+
+    console.log(`✅ Built API data:`);
+    console.log(`   - ${projects.length} projects processed`);
+    console.log(`   - ${categories.size} categories found`);
+    console.log(`   - Data written to api/data/`);
+
+    // Generate JavaScript module for GitHub Pages
+    const jsModule = `// Auto-generated Drupal Tools data
+window.DrupalToolsData = ${JSON.stringify(indexData, null, 2)};`;
+
+    await fs.writeFile(
+      path.join(outputDir, 'drupal-tools-data.js'),
+      jsModule
+    );
+
+    console.log(`   - JavaScript module created for GitHub Pages`);
+
+  } catch (error) {
+    console.error('❌ Error building API data:', error);
+    process.exit(1);
+  }
+}
+
+buildApiData();

_scripts/watch-api.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+// Watch for changes in _data/projects and rebuild API data
+import fs from 'fs';
+import path from 'path';
+import { exec } from 'child_process';
+
+const projectsDir = '_data/projects';
+
+console.log('Watching for changes in _data/projects...');
+console.log('Press Ctrl+C to stop\n');
+
+// Initial build
+console.log('Building initial API data...');
+exec('node _scripts/build-api-data.js', (error, stdout, stderr) => {
+  if (error) {
+    console.error('Build error:', error);
+    return;
+  }
+  console.log(stdout);
+});
+
+// Watch for file changes
+fs.watch(projectsDir, { recursive: true }, (eventType, filename) => {
+  if (filename && (filename.endsWith('.yml') || filename.endsWith('.yaml'))) {
+    console.log(`\n📝 Detected change in: ${filename}`);
+
+    // Debounce rapid changes
+    setTimeout(() => {
+      console.log('🔄 Rebuilding API data...');
+      exec('node _scripts/build-api-data.js', (error, stdout, stderr) => {
+        if (error) {
+          console.error('❌ Build error:', error.message);
+          return;
+        }
+        console.log('✅ ' + stdout);
+      });
+    }, 500);
+  }
+});