ednark/mcp-drupal-ts

MCP Drupal Documentation Server

A Model Context Protocol (MCP) server that provides tools and resources for searching and accessing Drupal and PHP documentation.

Overview

This project implements an MCP server that allows AI assistants to search and retrieve information from Drupal and PHP documentation. It follows a strict Test-Driven Development (TDD) approach to ensure high code quality and comprehensive test coverage.

Features

• MCP server implementation following the Model Context Protocol specification
• Tools for searching Drupal and PHP documentation
• Resources for accessing documentation content
• Custom file-based vector database integration for semantic search
• Comprehensive test suite with high coverage

Project Structure

mcp-drupal-ts/
├── src/                  # Source code
│   ├── mcp/              # MCP server implementation
│   │   ├── tools/        # MCP tools
│   │   └── resources/    # MCP resources
│   ├── types/            # TypeScript type definitions
│   └── index.ts          # Entry point
├── tests/                # Test files
│   ├── unit/             # Unit tests
│   └── integration/      # Integration tests
├── docs/                 # Documentation
│   └── README.md         # Documentation index
└── README.md             # This file

Test-Driven Development

This project follows a strict Test-Driven Development (TDD) approach. All features and bug fixes must be implemented following the TDD process:

1. Write tests first
2. Run tests to verify they fail
3. Implement minimal code to make tests pass
4. Refactor while maintaining passing tests

For detailed information about the TDD process in this project, see the .

Getting Started

Prerequisites

• Node.js 18 or higher
• npm 8 or higher

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/mcp-drupal-ts.git
   cd mcp-drupal-ts
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Running Tests

Run all tests:

npm test

Run unit tests only:

npm run test:unit

Run integration tests only:

npm run test:integration

Generate coverage report:

npm run test:coverage

Running the Server

Start the MCP server:

npm start

For development with automatic rebuilding:

npm run dev

Usage

The MCP server can be used by AI assistants that support the Model Context Protocol. It provides tools and resources for searching and accessing Drupal and PHP documentation.

MCP Server for RooCode

This project can be used as an MCP server for RooCode, providing semantic search capabilities for PHP and Drupal documentation. For detailed instructions, see the .

Documentation Pipeline

The project includes a documentation pipeline that collects, processes, and imports Drupal and PHP documentation:

1. Collect documentation from sources

   npm run collect-php-docs
   npm run collect-drupal-docs
   

2. Convert documentation to markdown format

   npm run markdown-php-docs
   npm run markdown-drupal-docs
   

3. Import documentation into the database

   npm run import-docs
   

4. Run the entire pipeline

   npm run docs-pipeline
   

Vector Search

The project uses a custom file-based vector database for semantic search capabilities:

1. Search documentation with semantic search

   npm run search-docs -- "your search query"
   

The vector database is a simple JSON-based storage system that doesn't require a separate server process.

For more details about the vector database integration, see the .

Vector Database Release Management

This project implements a release-based distribution approach for vector database files. Instead of storing large vector database files in the Git repository, they are managed through GitHub releases and downloaded automatically when needed.

Architecture Overview

The vector database release system consists of several components:

1. Version Management: A vector-db-version.json file tracks metadata about vector files, including versions, checksums, and compatibility information
2. Development Setup: Tools to set up a development environment with the necessary vector files
3. Release Building: Scripts to build and publish new vector database releases
4. Deployment: Scripts to ensure vector files are present during deployment
5. CI/CD Integration: GitHub Actions workflows to automate the release process

This approach provides several benefits:

• Keeps the Git repository small and manageable
• Ensures all developers use the same vector database files
• Provides versioning and compatibility checks
• Enables easy updates with integrity verification

Vector Database Version System

The system uses semantic versioning for vector database releases, independent from the main application version. Vector file metadata is stored in vector-db-version.json:

{
  "version": "0.1.0",           // Semantic version of the vector database
  "releaseDate": "2025-05-12",  // Last update date
  "compatibility": {            // App version compatibility range
    "minAppVersion": "0.1.0",
    "maxAppVersion": null
  },
  "files": {                    // Vector files included in this version
    "drupal-vectors.json": {
      "size": 0,
      "checksum": "",
      "lastUpdated": "2025-05-12",
      "description": "Drupal documentation vector embeddings"
    },
    "php-vectors.json": {
      "size": 0,
      "checksum": "",
      "lastUpdated": "2025-05-12",
      "description": "PHP documentation vector embeddings"
    }
  },
  "repositoryInfo": {           // Repository information for downloads
    "owner": "your-github-username",
    "repo": "mcp-drupal-ts",
    "releasesUrl": "https://github.com/your-github-username/mcp-drupal-ts/releases"
  }
}

When the application runs, it checks for these vector files and downloads them if they're missing or corrupted.

Development Workflow

Setting Up the Development Environment

When you first clone the repository or need to refresh your vector files:

# Install dependencies and auto-setup vector files (runs after npm install)
npm install

# Or manually set up the development environment
npm run setup:dev

# Force redownload of all vector files
npm run setup:dev:force

The setup script:

1. Checks if vector database files are present
2. Downloads missing files from GitHub releases
3. Verifies file integrity using checksums
4. Reports the status of all files

Creating a New Vector Database Release

When you need to create a new vector release (e.g., after updating embeddings):

# Build a release with patch version increment (0.1.0 → 0.1.1)
npm run vector:build-release:patch

# Build a release with minor version increment (0.1.0 → 0.2.0)
npm run vector:build-release:minor

# Build a release with major version increment (0.1.0 → 1.0.0)
npm run vector:build-release:major

# Or specify the increment type as an argument
npm run vector:build-release -- minor

The release builder:

1. Increments the version based on the specified type
2. Updates file metadata (size, checksum, date)
3. Creates a release bundle in the dist/vector-release directory
4. Provides instructions for publishing the release on GitHub

After building:

1. Commit the updated vector-db-version.json file
2. Tag the commit with vector-db-v{version} (e.g., vector-db-v0.2.0)
3. Create a GitHub release with the files from dist/vector-release

Deploying with Vector Files

When deploying the application:

# Deploy with automatic vector file management
npm run deploy

# Or directly
bash scripts/deploy-with-vectors.sh

The deployment script:

1. Reads the vector database version information
2. Checks for each required vector file
3. Downloads missing files from GitHub releases
4. Continues with the deployment process

This ensures that all necessary vector files are available before the application starts.

CI/CD with GitHub Actions

The project includes a GitHub Actions workflow for automated vector database releases:

Manual Trigger

You can manually trigger a release from the GitHub Actions tab:

1. Select the "Vector Database Release" workflow
2. Click "Run workflow"
3. Choose a version increment type (major, minor, patch)
4. Optionally enable automatic GitHub release creation

Automatic Trigger

Pushing a tag with the format vector-db-v* (e.g., vector-db-v0.2.0) will also trigger the workflow:

git tag vector-db-v0.2.0
git push origin vector-db-v0.2.0

The workflow:

1. Builds the application
2. Generates vector database files (if manually triggered)
3. Updates version information
4. Creates a GitHub release with the vector files
5. Optionally commits changes to the version file

NPM Script Reference

Vector Database Management:

• setup:dev: Set up development environment with vector files
• setup:dev:force: Force redownload all vector files
• vector:build-release: Build vector release (default: patch)
• vector:build-release:patch: Build vector release with patch increment
• vector:build-release:minor: Build vector release with minor increment
• vector:build-release:major: Build vector release with major increment
• deploy: Deploy with automatic vector file management

Related Documentation Scripts:

• docs-pipeline: Run the complete documentation processing pipeline
• import-docs: Import documentation into vector database
• search-docs: Search documentation using semantic search

Troubleshooting Common Issues

Missing Vector Files

• Issue: Application reports missing vector files
• Solution: Run npm run setup:dev to download vector files

Checksum Validation Failure

• Issue: Vector file fails checksum validation
• Solution: Run npm run setup:dev:force to force redownload all files

GitHub Release Not Found

• Issue: Cannot download vector files from GitHub release
• Solution: Check that the repository information in vector-db-version.json is correct and that the GitHub release exists

Permission Denied for deploy-with-vectors.sh

• Issue: Cannot execute the deployment script
• Solution: Make the script executable with chmod +x scripts/deploy-with-vectors.sh

jq Not Found Error in Deployment Script

• Issue: Deployment script reports jq not found
• Solution: This is just a warning; the script will fall back to Node.js for JSON parsing

Semantic Search via MCP

The vector database powers a semantic search tool that is exposed through the MCP server. This allows AI assistants like RooCode to perform semantic searches on the documentation:

{
  "id": "789",
  "jsonrpc": "2.0",
  "method": "call_tool",
  "params": {
    "name": "semantic-docs-search",
    "arguments": {
      "query": "How to apply a function to each element of an array?"
    }
  }
}

The MCP server can be used by AI assistants that support the Model Context Protocol. It provides tools and resources for searching and accessing Drupal and PHP documentation.

Example Tool Usage

{
  "id": "123",
  "jsonrpc": "2.0",
  "method": "call_tool",
  "params": {
    "name": "drupal-docs-search",
    "arguments": {
      "query": "hook_form_alter"
    }
  }
}

Example Resource Access

{
  "id": "456",
  "jsonrpc": "2.0",
  "method": "read_resource",
  "params": {
    "uri": "drupal-docs://api/hook_form_alter"
  }
}

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch
3. Follow the TDD process (write tests first!)
4. Submit a pull request

For more details, see the .

Development Guidelines

• Follow the TDD process for all changes
• Maintain high test coverage (minimum 80%)
• Follow TypeScript best practices
• Use ESLint for code quality

License

This project is licensed under the MIT License - see the file for details.

Acknowledgments

• The Model Context Protocol team for the MCP specification
• The Drupal community for their excellent documentation