Global Executables MCP Server

Why this exists

A package name is not necessarily the command it installs. Searching registries for package names can miss a collision such as a differently named package that already ships your proposed command.

The index preserves the relationship that matters:

command → provider → package → ecosystem → source evidence

Try it now—no installation

Open the Index Playground to check a name, find similar commands, inspect providers, or review source coverage. The Playground reads the same public JSON dataset as the MCP server, and query data is not sent to a third-party API.

For an AI-assisted check, connect the MCP server below and ask:

I am naming a new CLI. Check `envc`, `evcr`, `evpk`, and `envcp` for exact
collisions and confusingly similar commands. Keep rejected names internal and
explain the coverage caveat for every survivor.

The agent can reject envcp with evidence instead of relying on a package-name search: the command is provided on PyPI by both chaperone and envcp.

What you get

The server has no write tools and never installs or executes the software it finds.

Quick start

1. Install uv

The recommended setup uses uv. You do not need to clone this repository, download the dataset, or create an API key.

Verify that uvx is available:

uvx --version

2. Add the MCP server

Choose your client below. The first launch downloads the package from PyPI; later launches reuse uv's cache.

Add this to claude_desktop_config.json, ~/.cursor/mcp.json, or a project's .cursor/mcp.json:

{
  "mcpServers": {
    "global-executables": {
      "command": "uvx",
      "args": ["global-executables", "mcp"]
    }
  }
}

claude mcp add global-executables -- uvx global-executables mcp

codex mcp add global-executables -- uvx global-executables mcp

Start a new Codex session after adding the server. See the Codex setup tutorial for registration checks and a source-checkout setup.

Add this to .vscode/mcp.json:

{
  "servers": {
    "global-executables": {
      "type": "stdio",
      "command": "uvx",
      "args": ["global-executables", "mcp"]
    }
  }
}

Use this server entry instead of the uvx entry:

{
  "command": "docker",
  "args": ["run", "-i", "--rm", "ghcr.io/asopitech-labs/global-executables-mcp:latest"]
}

The image is public and contains the server, but not a stale copy of the dataset.

3. Ask your agent

Try one of these prompts:

Is the command name `envc` already taken? Check similar names too.

Check `envc`, `evcr`, `evpk`, and `envcp` as possible CLI names. Do not show
rejected candidates; explain the dataset coverage for the survivors.

Which package provides the `ruff` executable, and how should I install it in a
Python 3.12 project virtual environment?

The agent will normally call check_executables for a batch and search_similar_executables for the candidates that remain.

[!IMPORTANT] found: true means a collision. found: false means only that the current snapshot contains no match. When status is unknown, partial source coverage means the name is not proven to be available. Read warnings, absence.confidence, and coverage_scope before adopting a name.

How it works

Snapshot lookups fetch only the public dictionary branch files a query needs, cache them in the current user's cache directory, and revalidate them with ETag. Cached files remain usable when the network is temporarily unavailable.

uvx global-executables mcp --help lists the same options as flags. The package is published to PyPI from release 1.3.0. See the MCP guide for HTTP transport, offline operation, and running from a source checkout.

MCP tools at a glance

Snapshot lookup tools are read-only. discover_published_package makes bounded live registry and artifact requests without executing package code. On a designated runner configured with Git write access, successful verification also reserves an immutable intake/<id> branch for central revalidation. The result reports reservation.status; an unconfigured copy reports unavailable and does not claim publication. Neither MCP nor CLI writes the published dictionary directly. The repository's Verify and reserve published package discovery GitHub Actions workflow is the designated runner; it invokes both CLI and MCP before the collector. Installation resolvers return instructions; they never install or execute software. Full inputs and result contracts are documented in the MCP guide.

The scheduled intake collector validates and rechecks reserved evidence before merging it into artifact-data. The regular refresh remains the only writer of the dictionary branch. See the MCP guide for runner configuration and the reservation lifecycle.

Supported ecosystems

Every provider keeps its source and a confidence level (direct, filesystem, or inferred). Coverage differs by ecosystem, so negative results carry explicit coverage metadata instead of pretending that every registry is exhaustive. See Data Sources for collection details and coverage and freshness for the result contract.

Documentation map

Troubleshooting

Install uv, confirm that uvx --version works in a new terminal, and restart the MCP client so it receives the updated PATH. If the client uses a restricted environment, set the configuration's command to the absolute path reported by command -v uvx (macOS/Linux) or where uvx (Windows).

Restart the client or begin a new agent session after changing its MCP configuration. Then check the client logs for JSON syntax errors or a failed uvx launch. Codex users can run codex mcp list and codex mcp get global-executables; Claude Code users can run claude mcp list.

Offline mode can serve only files that earlier queries placed in the cache. Reconnect once and run the needed queries, or point GLOBAL_EXECUTABLES_DATASET_ROOT at a local checkout of the dictionary branch. See local stdio setup.

That is expected whenever the relevant ecosystems are not exhaustively covered. It means “not found in this snapshot,” not “safe to claim.” Use get_coverage, check similar names, and perform additional registry and web searches before publishing.

---

Goals

Global Executables aims to provide:

• a public dataset of real-world executable names;
• cross-ecosystem coverage;
• traceable provenance for every collected executable;
• reproducible dataset generation;
• Git-friendly structured data;
• machine-readable indexes for efficient lookup;
• historical tracking of executable names;
• MCP access for AI agents;
• explicit dataset coverage and freshness information.

The dataset itself is the primary artifact.

The MCP server is an access layer over that public data, not the source of truth.

Try the live Index Playground to inspect crawl progress and run read-only check, search, similar, coverage, and assess queries directly in a browser. The playground is a static GitHub Pages client over the public JSON dataset; no query data is sent to a third-party API.

The program and published data have independent lifecycles. Program source, schemas, tests, and documentation live on main; the generated JSON dictionary lives on the orphan dictionary branch. The stable raw-data base URL is:

https://raw.githubusercontent.com/asopitech-labs/global-executables/dictionary

See the dictionary branch migration note for the branch contract, local setup, and the main URL cutover.

Go development follows the JetBrains Modern Go Guidelines. See the Go crawler development and build contract for the versioned review, build, test, security, and release workflow.

---

Architecture

Package ecosystems
        │
        ├── Debian / Ubuntu
        ├── Arch Linux
        ├── Homebrew
        ├── npm
        ├── PyPI
        ├── crates.io
        ├── Go modules
        ├── RubyGems
        ├── Packagist / Composer
        ├── ConanCenter
        ├── vcpkg
        ├── xmake-repo
        └── others
                │
                ▼
          GitHub Actions (`main`)
                │
       collect / normalize
                │
                ▼
  `dictionary` branch dataset
                │
        ┌───────┴────────┐
        │                │
        ▼                ▼
   GitHub / raw        MCP Server
      data                │
                          ▼
                     AI agents

GitHub Actions periodically collects upstream package information, normalizes executable records, regenerates indexes, validates the dataset, and publishes the resulting files.

---

Data Model

The canonical unit is an executable name.

Each executable is represented by a structured file containing its known providers.

Conceptually:

{
  "command": "example",
  "providers": [
    {
      "ecosystem": "example-ecosystem",
      "package": "example-package",
      "version": "1.0.0",
      "repository": "https://example.com/repository",
      "source": "example-source",
      "confidence": "direct"
    }
  ],
  "first_seen": "2026-08-14",
  "last_seen": "2026-08-14"
}

A single executable may have multiple providers across multiple ecosystems.

---

Repository Layout

The dictionary branch contains only published artifacts:

dictionary/
├── data/
│   ├── executables/
│   │   ├── en/
│   │   │   ├── envc.json
│   │   │   └── envcp.json
│   │   └── gi/
│   │       └── git.json
│   │
│   ├── indexes/
│   │   ├── prefix/
│   │   ├── length/
│   │   ├── ecosystem/
│   │   └── trigram/
│   │
│   ├── metadata.json
│   └── history.json
└── reports/
    ├── production-crawl.json
    └── production-refresh.json

The main branch separately keeps fixtures/, schema/, src/, tools/, tests/, docs/, playground/, and .github/workflows/; it does not track the generated paths above. The canonical dataset uses ordinary structured files rather than requiring a database server.

Derived indexes are reproducible and may be regenerated from the canonical executable records.

---

Lookup

Exact lookup maps directly to the repository structure.

For example:

envcp
  ↓
prefix: en
  ↓
data/executables/en/envcp.json

This allows consumers to retrieve individual records without downloading or querying a centralized database.

Derived indexes support broader queries such as:

• prefix;
• executable length;
• ecosystem;
• similar names.

---

Data Sources

Collectors are independent for each ecosystem.

Potential sources include:

C and C++ have no single registry, so three recipe repositories are read instead, and each contributes the strongest evidence it actually carries. vcpkg names the tools a port installs, because naming them is what installs them. ConanCenter recipes never name their executables, so the built package's own file list is read. xmake declares that a package is a binary but never what the binary is called, so its records are marked inferred and no xmake record should be read as a declaration. None of the three is exhaustive: a vcpkg port can install a command without declaring it, a ConanCenter recipe nobody has built states nothing about installed files, and an xmake package can install a command under another name.

The project records how each executable was discovered rather than treating all observations as equally authoritative.

---

Confidence

Records may carry a confidence level describing how an executable name was established.

For example:

direct
filesystem
inferred

direct means the executable is explicitly declared by package metadata.

filesystem means it was observed in package contents as an installed executable.

inferred means it was derived indirectly and should be treated with lower confidence.

Consumers can use this information when deciding whether a potential naming collision is significant.

---

Installation guidance

resolve_installation and resolve_installations provide environment-specific installation guidance. Agents can call these MCP tools directly; people can enter the same target context in the browser Playground. The CLI exposes the resolver against a local dictionary too:

global-executables resolve-installation pygo --root ./dictionary \
  --environment '{"package_manager":"pip","runtime_version":"3.12","install_scope":"project","virtualenv_bin":"./.venv/bin"}'

The MCP guide documents the required target context and the installation-v1 result contract. Guidance without target-specific install-and-invoke validation is marked unverified. The method validation record distinguishes tested package-manager syntax from untested package identities.

---

Agent Workflow

A naming agent should use Global Executables before presenting CLI name recommendations.

Recommended workflow:

Generate candidate names internally
            │
            ▼
     check_executables
            │
            ▼
 Separate `found:true` collisions from `found:false` observations
            │
            ▼
 search_similar_executables for not-found candidates
            │
            ▼
 Remove confusing candidates
            │
            ▼
 Present surviving names

Rejected candidates do not need to be surfaced to the user.

The purpose of the service is to make collision checking part of the agent's normal reasoning workflow rather than a manual follow-up task.

---

Result Semantics

Absence from the dataset does not prove that an executable name has never been used.

Results therefore distinguish the factual observation from confidence in absence:

collision
clear_in_index
unknown

For example:

{
  "name": "evpk",
  "found": false,
  "status": "unknown",
  "snapshot": "2026-10-19",
  "coverage_scope": "unknown",
  "checked_sources": [
    "arch",
    "crates",
    "debian",
    "go",
    "homebrew",
    "npm",
    "pypi",
    "ubuntu"
  ],
  "searched_sources": [
    "arch",
    "crates",
    "debian",
    "go",
    "homebrew",
    "npm",
    "pypi",
    "ubuntu"
  ],
  "coverage": {
    "arch": {
      "status": "success",
      "coverage_kind": "exhaustive",
      "records": 1647,
      "source": "data/production/intermediate/arch.jsonl"
    },
    "npm": {
      "status": "success",
      "coverage_kind": "partial",
      "records": 127,
      "source": "data/production/intermediate/npm.jsonl",
      "scope": "ecosyste.ms critical npm population covering 80% of downloads or dependent repositories",
      "catalog_complete": true,
      "catalog_packages": 2295,
      "catalog_snapshot": "2026-10-18",
      "catalog_source": "https://packages.ecosyste.ms/critical?registry=npmjs.org",
      "catalog_digest": "sha256:4b610ce561d63b72b7a4137ed75ba5ecbec5fbafda236218fc4264c92db605b3"
    }
  },
  "warnings": [
    {
      "code": "npm_coverage_incomplete",
      "ecosystem": "npm",
      "message": "npm coverage is incomplete or limited to a declared population. A missing result is not proof that no npm package uses this executable and is not permission to adopt the name.",
      "coverage": {
        "status": "success",
        "coverage_kind": "partial",
        "source": "data/production/intermediate/npm.jsonl",
        "scope": "ecosyste.ms critical npm population covering 80% of downloads or dependent repositories",
        "catalog_complete": true,
        "catalog_packages": 2295,
        "catalog_snapshot": "2026-10-18",
        "catalog_source": "https://packages.ecosyste.ms/critical?registry=npmjs.org",
        "catalog_digest": "sha256:4b610ce561d63b72b7a4137ed75ba5ecbec5fbafda236218fc4264c92db605b3"
      },
      "reference": "https://github.com/asopitech-labs/global-executables/issues/54"
    }
  ],
  "absence": {
    "status": "not_found_in_current_index",
    "confidence": "insufficient_coverage",
    "searched_sources": [
      "arch",
      "crates",
      "debian",
      "go",
      "homebrew",
      "npm",
      "pypi",
      "ubuntu"
    ]
  }
}

found:false means that the name was not found in the current index. unknown means the available coverage is insufficient to make an exhaustive absence claim; it does not mean that the query was unavailable. clear_in_index is returned only when every source in the queried snapshot has coverage_kind: exhaustive, a successful run, and no finite population limit (scope or catalog_* fields). A completed npm critical catalog sets catalog_complete: true and keeps coverage_kind: partial; it never makes the snapshot exhaustive. Incomplete npm coverage also adds a npm_coverage_incomplete warning. None of these statuses is permission to adopt a name.

The coverage object reports the per-source collection status, coverage kind, and record count. The example shows two representative sources; the live response includes all sources in the snapshot (and may also include each source's input path).

It does not mean that the name is legally or globally guaranteed to be available.

---

Coverage and Freshness

Dataset metadata records:

• generation timestamp;
• snapshot identifier;
• number of indexed executables;
• enabled collectors;
• freshness of each upstream source;
• collector status.

This information is available both as structured data and through MCP.

Agents can therefore evaluate the strength of a lookup result instead of treating the index as complete by assumption.

---

GitHub as the Source of Truth

Global Executables deliberately keeps its canonical data in the repository's orphan dictionary branch.

This provides:

• transparent provenance;
• reviewable changes;
• reproducible generation;
• historical tracking;
• forks and mirrors;
• direct raw-file access;
• independence from the availability of the MCP service.

If the hosted MCP endpoint disappears, the dataset remains usable.

A third party can build another MCP server, search engine, CLI, or analysis tool directly from the repository.

---

Automation

GitHub Actions maintains the dataset.

The general pipeline is:

scheduled / manual trigger
          │
          ▼
     run collectors
          │
          ▼
       normalize
          │
          ▼
        merge
          │
          ▼
 generate executable files
          │
          ▼
    generate indexes
          │
          ▼
       validate
          │
          ▼
        publish

Collectors should contain the actual collection logic independently of GitHub Actions so they can also be executed and tested locally.

act may be used during development to run compatible GitHub Actions workflows locally.

---

What Global Executables Is Not

Global Executables is not:

• a trademark search service;
• a brand-name availability service;
• a package registry;
• a package manager;
• a vulnerability database;
• a software catalog;
• proof that an unused name is legally available.

It answers a narrower question:

What executable names are known to be used across the software ecosystems covered by the dataset?

Trademark, company-name, domain, repository-name, and broader web searches remain separate checks.

---

Potential Uses

Beyond CLI naming, the dataset can support:

• automated CLI naming assistants;
• repository CI policies;
• package publishing checks;
• ecosystem collision analysis;
• executable discovery;
• historical studies of CLI ecosystems;
• IDE and developer-tool integrations;
• AI-agent preflight checks.

---

Project Principle

Public data first. MCP second.

The value of Global Executables is not tied to a particular server implementation.

The durable asset is the openly available, reproducible, cross-ecosystem executable-name dataset.

MCP makes that dataset immediately useful to agents.

Current implementation

The schemas, deterministic builder, production OS index collector, derived prefix/length/ecosystem/trigram and logical-scope indexes, collector parsers, local/HTTP MCP server with Git intake for verified npm/PyPI discovery, assessment API, bounded fixture freshness scenarios, and CI checks are implemented in this repository. Coverage is measured against each source. npm stays coverage_kind: partial even when its finite ecosyste.ms critical catalog finishes (catalog_complete: true); the all-registry npm long tail is not in the index. See docs/DATA_MODEL.md for exact naming, sharding, alias, and history rules and docs/OPERATIONS.md for reproducible commands, freshness-state scenarios, and honest measured coverage limitations.

For zero-setup use, see Quick start. To query a pinned snapshot without network access, install the program, materialize the published branch in a separate worktree, and point the server at it:

python -m pip install -e .
git fetch origin dictionary
git worktree add .dictionary origin/dictionary
global-executables-mcp --root . --dataset-root .dictionary

Use --transport streamable-http for remote access. Both modes expose check_executable, check_executables, get_executable, search_executables, search_similar_executables, get_coverage, assess_executable, and assess_executables; neither mode exposes writes. Data is reusable under the repository license by reading the canonical JSON directly from the dictionary branch, without running MCP. See docs/MCP.md for local client configuration, the remote endpoint, resources, health visibility, and the survivor-only agent workflow.

The manual fixture workflow exercises a bounded incremental freshness scan. It rotates through immutable test partitions, persists a cursor and last successful observations on the freshness-data branch, and publishes a machine-readable test report. It is not production freshness or a full dataset refresh. Coverage is snapshot-specific and reported by get_coverage. The published snapshot contains production OS/Homebrew coverage, a completed but partial npm critical catalog (catalog_complete, not registry-wide exhaustiveness), and partial coverage for other registries such as PyPI and Go; it is not full global ecosystem coverage, so consumers must preserve clear_in_index/unknown semantics and the npm_coverage_incomplete warning.

Registry artifact inspection is separately resumable. CI refreshes the finite npm critical catalog and crawls it to 100% daily, while dedicated local containers advance PyPI and Go module cursors and publish checkpoints to artifact-data; these local containers are temporary completion boosters and stop at 100%. After a source reaches 100%, a six-hour GitHub Actions matrix cycles through every indexed package with a persisted refresh cursor. Successful results replace stale package observations, including commands removed by a newer release. CI also performs one daily crates.io dump change check and downloads the dump only when it changed. The CI refresher dispatches a dictionary rebuild only when normalized observations changed and redeploys Pages whenever it publishes crawl progress. Go modules, npm, PyPI, RubyGems, and Packagist use the transactional Go runtime; their bbolt state commits cursor, retry verdicts, and observations together. CI regenerates npm's bounded population; PyPI, RubyGems, and Packagist reuse sampled catalogs, while Go extends its index. Finishing a declared catalog may set catalog_complete; npm is never promoted to coverage_kind: exhaustive from that catalog alone. Other sources become exhaustive only after their declared catalog and required artifact inspections complete successfully without a finite population limit.

Successful collection does not by itself permit a negative collision claim. Every valid query returns a factual found observation. Fixture, smoke, and partial snapshots return insufficient absence confidence for absent names; clear_in_index requires metadata explicitly marking the complete queried snapshot exhaustive. Derived search indexes are integrity-pinned in metadata and are used directly by prefix, length, ecosystem, and similarity queries.

For a clean-checkout setup, client configuration, expected responses, and verification steps, see docs/SETUP.md.

Issue completion and release evidence follow docs/RELEASE.md; implementation claims alone do not close work.

Data sources, their licenses and terms, and required attribution are listed in docs/DATA_SOURCES.md.