Node.js package bundling universal-ctags binaries for cross-platform code indexing
-[](LICENSE) -[](package.json) -[](#platform-support) +[](LICENSE) +[](package.json) +[](#platform-support)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 +| Capability | +Description | +
|---|---|
| Automatic Binary Management | +Downloads and configures platform-specific ctags binaries during npm install with zero configuration required. | +
| Cross-Platform Support | +Native binaries for Windows (x64/x86), macOS (Intel/Apple Silicon), and Linux (x64/ARM64). | +
| GitHub API Integration | +Respects GITHUB_TOKEN for rate limit management and supports offline fallback installation. | +
| MCP Ecosystem Ready | +Purpose-built for Model Context Protocol servers requiring universal-ctags functionality. | +
This package is published to GitHub Packages and requires authentication to install.
+ +| Step | +Instructions | +
|---|---|
| 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 Pattern | +Code 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 | +Architecture | +Binary Source | +
|---|---|---|
| Windows | +x64, x86 | +ctags-win32 | +
| macOS | +x64 (Intel), ARM64 (Apple Silicon) | +ctags-nightly-build | +
| Linux | +x64, ARM64 | +ctags-nightly-build | +
| 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+ |
+
| Phase | +Description | +
|---|---|
| Installation | +npm install triggers the postinstall script | +
| Platform Detection | +Determines operating system and CPU architecture | +
| Download | +Fetches appropriate binary from GitHub releases | +
| Extraction | +Extracts binary to the bin/ directory | +
| Permissions | +Sets executable permissions on Unix systems | +
| Verification | +Main module verifies binary existence before exporting path | +
| Variable | +Purpose | +Default | +
|---|---|---|
GITHUB_TOKEN |
+ GitHub API authentication to avoid rate limits | +None | +
SKIP_POSTINSTALL |
+ Skip automatic binary download during installation | +false | +
| 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+ |
+
| 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+ |
+
Comprehensive tests verify binary download, extraction, executable permissions, functionality, and tag generation capabilities.
+ +| CI/CD Workflows | +Purpose | +Platforms | +
|---|---|---|
| Platform Tests | +Automated testing on all supported platforms | +Windows, macOS (x64/ARM64), Linux | +
| Publish | +Publish package to GitHub Packages | +N/A | +
| Issue | +Solution | +
|---|---|
| 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
+ |
+
If automatic installation fails, install universal-ctags manually:
+ +| Platform | +Installation Command | +
|---|---|
| macOS | +brew install universal-ctags |
+
| Linux (Ubuntu/Debian) | +sudo apt install universal-ctags |
+
| Linux (Snap) | +sudo snap install universal-ctags |
+
| Windows | +Download from ctags-win32 releases | +
| Contributing | +License | +
|---|---|
|
+ 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 + |
+
| Project | +Contribution | +
|---|---|
| Universal Ctags | +Core ctags implementation | +
| ctags-win32 | +Windows binary distribution | +
| ctags-nightly-build | +Unix binary distribution | +
| vscode-ripgrep | +Package structure inspiration | +
Built for the Model Context Protocol ecosystem