From 314c7c82d3de18c261a51bcf0335dfad84b98ba4 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 22 Nov 2025 07:43:07 +0000 Subject: [PATCH 1/2] Professionalize README with centered table layout Complete rewrite of README.md following modern documentation standards: - Upgraded badges to "for-the-badge" style for better visibility - Restructured all content using centered tables for clean presentation - Removed bulleted lists and markdown blocks in favor of HTML tables - Individually centered all titles and descriptive text - Maintained all original content while improving readability - Removed emoji usage for professional appearance - Organized sections: Overview, Installation, Usage, Platform Support, Architecture, Configuration, Development, Troubleshooting, Contributing, License, and Acknowledgments --- README.md | 619 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 385 insertions(+), 234 deletions(-) diff --git a/README.md b/README.md index d950f51..a942dec 100644 --- a/README.md +++ b/README.md @@ -4,92 +4,132 @@ **Node.js package bundling universal-ctags binaries for cross-platform code indexing** -[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) -[![Node Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](package.json) -[![Platform Support](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)](#platform-support) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge)](LICENSE) +[![Node Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg?style=for-the-badge)](package.json) +[![Platform Support](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg?style=for-the-badge)](#platform-support) ---- - -## Overview - -`code-search-mcp-universal-ctags` provides pre-built universal-ctags binaries for Node.js projects, eliminating the need for manual installation. The package automatically downloads and configures the appropriate binary for your platform during installation. +
-This package is designed for use with the Model Context Protocol (MCP) and other code analysis tools that require universal-ctags functionality. +

Overview

---- +

Pre-built universal-ctags binaries for Node.js projects, eliminating manual installation complexity. The package automatically downloads and configures platform-specific binaries during installation, providing seamless code indexing capabilities for MCP servers and code analysis tools.

-## Features +
-| Feature | Status | Notes | -|---------|--------|-------| -| Automatic Binary Download | ✅ Full | Downloads during npm install | -| Cross-Platform Support | ✅ Full | Windows, macOS, Linux | -| Zero Configuration | ✅ Full | Works out of the box | -| ARM64 Support | ✅ Full | Native Apple Silicon and ARM Linux | -| Offline Fallback | ✅ Full | Manual installation instructions provided | -| GitHub Token Support | ✅ Full | Respects GITHUB_TOKEN for rate limits | +

Core Capabilities

+ + + + + + + + + + + + + + + + + + + + + + +
CapabilityDescription
Automatic Binary ManagementDownloads and configures platform-specific ctags binaries during npm install with zero configuration required.
Cross-Platform SupportNative binaries for Windows (x64/x86), macOS (Intel/Apple Silicon), and Linux (x64/ARM64).
GitHub API IntegrationRespects GITHUB_TOKEN for rate limit management and supports offline fallback installation.
MCP Ecosystem ReadyPurpose-built for Model Context Protocol servers requiring universal-ctags functionality.
---- - -## Installation - -### From GitHub Packages - -This package is published to GitHub Packages and requires authentication to install. - -#### Step 1: Create a GitHub Personal Access Token - -1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic) -2. Generate new token with `read:packages` scope -3. Copy the token - -#### Step 2: Configure npm Authentication - -Create or update `.npmrc` in your project root or home directory: - -``` -@LLMTooling:registry=https://npm.pkg.github.com -//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN -``` - -Replace `YOUR_GITHUB_TOKEN` with your personal access token. +
-#### Step 3: Install the Package +

Installation

-```bash -npm install @LLMTooling/code-search-mcp-universal-ctags -``` +
-**Alternative: Using environment variable** +
-```bash +

From GitHub Packages

+ +

This package is published to GitHub Packages and requires authentication to install.

+ + + + + + + + + + + + + + + + + + +
StepInstructions
1. Create GitHub Personal Access Token + Navigate to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
+ Generate new token with read:packages scope
+ Copy the generated token +
2. Configure npm Authentication + 
+# Create .npmrc in project root or home directory
+echo "@LLMTooling:registry=https://npm.pkg.github.com" > .npmrc
+echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN" >> .npmrc
+
3. Install the Package + 
npm install @LLMTooling/code-search-mcp-universal-ctags
+
+ +
+ + + + + + + + +
Alternative: Environment Variable Installation
+ 
 echo "@LLMTooling:registry=https://npm.pkg.github.com" > .npmrc
 export NODE_AUTH_TOKEN=YOUR_GITHUB_TOKEN
-npm install @LLMTooling/code-search-mcp-universal-ctags
-```
-
----
+npm install @LLMTooling/code-search-mcp-universal-ctags
+
-## Usage +
-### Basic Usage +
-```javascript +

Usage

+ + + + + + + + + + + + + + + + + + +
Usage PatternCode Example
Basic Usage + 
 const { ctagsPath } = require('@LLMTooling/code-search-mcp-universal-ctags');
 
 console.log('ctags binary location:', ctagsPath);
-// Use ctagsPath with child_process to run ctags commands
-```
-
-### With Child Process
-
-```javascript
+// Use ctagsPath with child_process to run ctags commands
+
With execSync + 
 const { execSync } = require('child_process');
 const { ctagsPath } = require('@LLMTooling/code-search-mcp-universal-ctags');
 
@@ -98,12 +138,15 @@ const version = execSync(`"${ctagsPath}" --version`, { encoding: 'utf8' });
 console.log(version);
 
 // Generate tags for a project
-execSync(`"${ctagsPath}" -R --fields=+nKz --extras=+q .`, { cwd: '/path/to/project' });
-```
-
-### With Spawn
-
-```javascript
+execSync(`"${ctagsPath}" -R --fields=+nKz --extras=+q .`, {
+  cwd: '/path/to/project'
+});
+
With spawn + 
 const { spawn } = require('child_process');
 const { ctagsPath } = require('@LLMTooling/code-search-mcp-universal-ctags');
 
@@ -115,92 +158,59 @@ ctags.stdout.on('data', (data) => {
 
 ctags.stderr.on('data', (data) => {
   console.error(`stderr: ${data}`);
-});
-```
+});
+
---- - -## Platform Support +
-| Platform | Architecture | Status | Binary Source | -|----------|--------------|--------|---------------| -| Windows | x64 | ✅ Supported | [ctags-win32](https://github.com/universal-ctags/ctags-win32) | -| Windows | x86 | ✅ Supported | [ctags-win32](https://github.com/universal-ctags/ctags-win32) | -| macOS | x64 (Intel) | ✅ Supported | [ctags-nightly-build](https://github.com/universal-ctags/ctags-nightly-build) | -| macOS | ARM64 (Apple Silicon) | ✅ Supported | [ctags-nightly-build](https://github.com/universal-ctags/ctags-nightly-build) | -| Linux | x64 | ✅ Supported | [ctags-nightly-build](https://github.com/universal-ctags/ctags-nightly-build) | -| Linux | ARM64 | ✅ Supported | [ctags-nightly-build](https://github.com/universal-ctags/ctags-nightly-build) | +

Platform Support

+ + + + + + + + + + + + + + + + + + + + + + +
PlatformArchitectureBinary Source
Windowsx64, x86ctags-win32
macOSx64 (Intel), ARM64 (Apple Silicon)ctags-nightly-build
Linuxx64, ARM64ctags-nightly-build
---- - -## Development - -### Prerequisites - -- Node.js >= 18.0.0 -- npm or yarn - -### Setup - -```bash -# Clone the repository -git clone https://github.com/LLMTooling/code-search-mcp-universal-ctags.git -cd code-search-mcp-universal-ctags - -# Install dependencies -npm install - -# Run tests -npm test - -# Run linter -npm run lint - -# Fix linting issues -npm run lint:fix -``` - -### Running Tests - -The package includes comprehensive tests that verify: - -- Binary download and extraction -- Binary executable permissions -- Binary functionality (version check) -- Tag generation capabilities - -```bash -npm test -``` - ---- - -## Testing Across Platforms - -The project includes GitHub Actions workflows for automated testing on all supported platforms: -
-| Workflow | Purpose | Trigger | -|----------|---------|---------| -| Platform Tests | Test on Windows, macOS (x64/ARM64), Linux | Manual, Push, PR | -| Publish | Publish to GitHub Packages | Manual, Release | +

Architecture

-To run platform tests manually, trigger the "Platform Tests" workflow from the GitHub Actions tab. - ---- - -## Architecture +
-### Package Structure +

Package Structure

-``` + + + + + + + +
File Tree
+ 
 code-search-mcp-universal-ctags/
 ├── lib/
 │   ├── index.js          # Main entry point
@@ -210,137 +220,278 @@ code-search-mcp-universal-ctags/
 │   └── basic.test.js     # Test suite
 ├── bin/                  # Created during install (git-ignored)
 │   └── ctags(.exe)       # Platform-specific binary
-└── package.json
-```
+└── package.json
+
-### How It Works +
-1. **Installation**: When you run `npm install`, the postinstall script executes -2. **Platform Detection**: Determines your OS and architecture -3. **Download**: Fetches the appropriate binary from GitHub releases -4. **Extraction**: Extracts the binary to the `bin/` directory -5. **Permissions**: Sets executable permissions on Unix systems -6. **Verification**: Main module verifies binary exists before exporting path +
---- +

How It Works

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PhaseDescription
Installationnpm install triggers the postinstall script
Platform DetectionDetermines operating system and CPU architecture
DownloadFetches appropriate binary from GitHub releases
ExtractionExtracts binary to the bin/ directory
PermissionsSets executable permissions on Unix systems
VerificationMain module verifies binary existence before exporting path
-## Environment Variables +
-| Variable | Purpose | Default | -|----------|---------|---------| -| `GITHUB_TOKEN` | GitHub API authentication (avoids rate limits) | None | -| `SKIP_POSTINSTALL` | Skip automatic binary download | `false` | +

Configuration

-### Using GITHUB_TOKEN - -To avoid GitHub API rate limits: +
-```bash +

Environment Variables

+ + + + + + + + + + + + + + + + + +
VariablePurposeDefault
GITHUB_TOKENGitHub API authentication to avoid rate limitsNone
SKIP_POSTINSTALLSkip automatic binary download during installationfalse
+ +
+ + + + + + + + +
Example Usage
+ 
+# Avoid GitHub API rate limits
 export GITHUB_TOKEN=your_github_token
 npm install
-```
-
-### Skipping Postinstall
-
-If you want to install the package without downloading the binary:
-
-```bash
-SKIP_POSTINSTALL=1 npm install
-```
-
----
-
-## Manual Installation
-
-If automatic installation fails, you can install universal-ctags manually:
-
-### macOS
-
-```bash
-brew install universal-ctags
-```
-
-### Linux (Ubuntu/Debian)
-
-```bash
-sudo apt install universal-ctags
-```
-
-### Linux (Snap)
 
-```bash
-sudo snap install universal-ctags
-```
+# Skip automatic binary download
+SKIP_POSTINSTALL=1 npm install
+
-### Windows - -Download the latest release from: -[https://github.com/universal-ctags/ctags-win32/releases](https://github.com/universal-ctags/ctags-win32/releases) - ---- - -## Troubleshooting +
-### Binary Not Found +
-If you see an error about the binary not being found: +

Development

-1. Ensure the postinstall script ran successfully -2. Check that the `bin/` directory exists -3. Try reinstalling: `rm -rf node_modules && npm install` + + + + + + + +
Setup & Testing
+ 
+# Clone the repository
+git clone https://github.com/LLMTooling/code-search-mcp-universal-ctags.git
+cd code-search-mcp-universal-ctags
 
-### Download Failures
+# Install dependencies
+npm install
 
-If the download fails:
+# Run tests
+npm test
 
-1. Check your internet connection
-2. Verify GitHub is accessible
-3. Try using a GITHUB_TOKEN to avoid rate limits
-4. Consider manual installation
+# Run linter
+npm run lint
 
-### Permission Errors (Unix)
+# Fix linting issues
+npm run lint:fix
+
-If you encounter permission errors: +
-```bash -chmod +x node_modules/@LLMTooling/code-search-mcp-universal-ctags/bin/ctags -``` +
---- +

Test Coverage

+ +

Comprehensive tests verify binary download, extraction, executable permissions, functionality, and tag generation capabilities.

+ + + + + + + + + + + + + + + + + +
CI/CD WorkflowsPurposePlatforms
Platform TestsAutomated testing on all supported platformsWindows, macOS (x64/ARM64), Linux
PublishPublish package to GitHub PackagesN/A
-## Contributing +
-Contributions are welcome! Please follow these guidelines: +
-1. Fork the repository -2. Create a feature branch -3. Make your changes -4. Run tests and linting -5. Submit a pull request +

Troubleshooting

+ + + + + + + + + + + + + + + + + + +
IssueSolution
Binary Not Found + Ensure postinstall script ran successfully
+ Verify bin/ directory exists
+ Try reinstalling: rm -rf node_modules && npm install +
Download Failures + Check internet connection and GitHub accessibility
+ Use GITHUB_TOKEN to avoid rate limits
+ Consider manual installation +
Permission Errors (Unix) + chmod +x node_modules/@LLMTooling/code-search-mcp-universal-ctags/bin/ctags +
---- +
-## License +
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. +

Manual Installation

+ +

If automatic installation fails, install universal-ctags manually:

+ + + + + + + + + + + + + + + + + + + + + + +
PlatformInstallation Command
macOSbrew install universal-ctags
Linux (Ubuntu/Debian)sudo apt install universal-ctags
Linux (Snap)sudo snap install universal-ctags
WindowsDownload from ctags-win32 releases
---- +
-## Acknowledgments +
-- [Universal Ctags](https://github.com/universal-ctags/ctags) - The main ctags project -- [ctags-win32](https://github.com/universal-ctags/ctags-win32) - Windows binaries -- [ctags-nightly-build](https://github.com/universal-ctags/ctags-nightly-build) - Unix binaries -- [vscode-ripgrep](https://github.com/microsoft/vscode-ripgrep) - Inspiration for package structure +

Contributing & License

+ + + + + + + + + + +
ContributingLicense
+ Fork the repository
+ Create a feature branch
+ Make changes and add tests
+ Run tests and linting
+ Submit a pull request + 		+ Released under the MIT License
+ See LICENSE file for details +
---- +
-**Built for the Model Context Protocol ecosystem** +

Acknowledgments

+ + + + + + + + + + + + + + + + + + + + + + +
ProjectContribution
Universal CtagsCore ctags implementation
ctags-win32Windows binary distribution
ctags-nightly-buildUnix binary distribution
vscode-ripgrepPackage structure inspiration
+ +
+ +

Built for the Model Context Protocol ecosystem

From 59a54eed23cc5b9b20b29d3fa1ecbf213554a40d Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 22 Nov 2025 07:53:03 +0000 Subject: [PATCH 2/2] Fix markdown header to use HTML tags for proper rendering Converted main title from markdown (#) to HTML (

) tag to ensure proper rendering in centered layout. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a942dec..6efd443 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@
-# code-search-mcp-universal-ctags +

code-search-mcp-universal-ctags

-**Node.js package bundling universal-ctags binaries for cross-platform code indexing** +

Node.js package bundling universal-ctags binaries for cross-platform code indexing

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge)](LICENSE) [![Node Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg?style=for-the-badge)](package.json)