Unified Artifact Index Interface (Pacman MCP Server)

This Model Context Protocol (MCP) service acts as a central gateway for interrogating various software package indexes. It furnishes Language Models with the capability to search, fetch details, and inspect artifacts across repositories such as PyPI (Python), npm (Node.js), crates.io (Rust), Docker Hub, and the Terraform Registry.

Exposed Functionality

search_package - Execute searches across multiple package indexes.
- index (string, mandatory): Target index identifier ("pypi", "npm", "crates", "terraform").
- query (string, mandatory): The search term or specific artifact name.
- limit (integer, optional): Constraint on the result set size (default is 5; cap is 50).
package_info - Retrieve comprehensive metadata for a specified artifact.
- index (string, mandatory): Index source ("pypi", "npm", "crates", "terraform").
- name (string, mandatory): The precise name of the package/module.
- version (string, optional): Specify a particular version; defaults to the latest release.
search_docker_image - Query repositories on Docker Hub for container images.
- query (string, mandatory): Image identifier or descriptive keywords.
- limit (integer, optional): Maximum number of returned images (default: 5, max: 50).
docker_image_info - Obtain granular details for a named Docker image.
- name (string, mandatory): Full image repository path (e.g., user/repository).
- tag (string, optional): Target image tag; defaults to 'latest'.
terraform_module_latest_version - Fetch the most recent version tag for a Terraform module.
- name (string, mandatory): Module identifier following the format: namespace/name/provider.

Specialized Prompts (High-Level Abstractions)

search_pypi: Locate Python libraries on the PyPI index.
Arguments: query (string, required).
pypi_info: Obtain specifics for a known Python package.
Arguments: name (string, required), version (string, optional).
search_npm: Find Node.js packages within the npm ecosystem.
Arguments: query (string, required).
npm_info: Retrieve data for a specific npm package.
Arguments: name (string, required), version (string, optional).
search_crates: Discover Rust crates hosted on crates.io.
Arguments: query (string, required).
crates_info: Get details for a particular Rust crate.
Arguments: name (string, required), version (string, optional).
search_docker: Enumerate Docker images matching a pattern in Docker Hub.
Arguments: query (string, required).
docker_info: Inspect a specific Docker image reference.
Arguments: name (string, required), tag (string, optional).
search_terraform: Look up configuration modules in the Terraform Registry.
Arguments: query (string, required).
terraform_info: Get metadata for a specific Terraform module.
Arguments: name (string, required).
terraform_latest_version: Determine the current stable version for a Terraform module.
Arguments: name (string, required).

Deployment Methods

Preferred Method: uv/uvx Integration

When utilizing uv for environment management, direct execution via uvx is the recommended approach, negating a formal installation step.

Traditional Installation via PIP

Alternatively, the server component can be installed using pip:

pip install mcp-server-pacman

Execution follows installation via the module runner:

python -m mcp_server_pacman

Containerized Operation

The service is also packaged for container environments:

docker pull oborchers/mcp-server-pacman:latest
docker run -i --rm mcp-server-pacman

Configuration for Consumers

Claude.app Setup

Integrate this server by updating your Claude configuration JSON:

Using uvx Runner

"mcpServers": {
  "pacman": {
    "command": "uvx",
    "args": ["mcp-server-pacman"]
  }
}

Using Docker Image

"mcpServers": {
  "pacman": {
    "command": "docker",
    "args": ["run", "-i", "--rm", "oborchers/mcp-server-pacman:latest"]
  }
}

Using Local PIP Install

"mcpServers": {
  "pacman": {
    "command": "python",
    "args": ["-m", "mcp_server_pacman"]
  }
}

VS Code Integration

For local debugging or development, adjust your VS Code User Settings JSON (or a workspace-specific .vscode/mcp.json file, requiring the top-level mcp key):

VS Code: uvx Configuration

{
  "mcp": {
    "servers": {
      "pacman": {
        "command": "uvx",
        "args": ["mcp-server-pacman"]
      }
    }
  }
}

Customizing the Request Identity (User-Agent)

The server defaults to this identifier for outgoing HTTP calls:

ModelContextProtocol/1.0 Pacman (+https://github.com/modelcontextprotocol/servers)

This can be overridden by appending the --user-agent=YourCustomID flag to the args list in your configuration.

Development Workflow

Running Automated Checks

Execute full test suite: uv run pytest -xvs
Targeted test execution: ``` # All provider-related tests uv run pytest -xvs tests/providers/

# Specific integration test file uv run pytest -xvs tests/integration/test_pypi_integration.py

# Specific test class within a file uv run pytest -xvs tests/providers/test_npm.py::TestNPMFunctions

# Single test method invocation uv run pytest -xvs tests/providers/test_pypi.py::TestPyPIFunctions::test_search_pypi_success ```

Style and Linting verification: uv run ruff check . uv run ruff format --check .
Code Formatting Correction: uv run ruff format .

Debugging Session Initiation

Use the MCP inspector utility for debugging sessions. For uvx installations:

npx @modelcontextprotocol/inspector uvx mcp-server-pacman

If running from a local source directory (e.g., during active development):

cd path/to/pacman
npx @modelcontextprotocol/inspector uv run mcp-server-pacman

Release Strategy

Automated releases are managed via GitHub Actions triggered by Git tags:

Increment the version number specified in pyproject.toml.
Create a new annotated tag, strictly following semantic versioning (e.g., git tag v1.2.3).
Push the tag to the remote repository: git push --tags.

This action sequence automatically ensures version alignment, runs validation checks, builds artifacts, publishes to PyPI, and updates the Docker Hub images (:latest and :X.Y.Z).

Source Code Organization

The repository architecture is organized as follows:

src/mcp_server_pacman/ # Root of the application code
├── models/             # Schema definitions and data structures
├── providers/          # Adapter layer for external registries
│   ├── pypi.py         # PyPI connector logic
│   ├── npm.py          # npm registry client
│   ├── crates.py       # crates.io interaction functions
│   ├── dockerhub.py    # Docker registry interface
│   └── terraform.py    # Terraform Registry interface functions
├── utils/              # General utilities and shared components
│   ├── cache.py        # Implementation of persistence/caching mechanisms
│   ├── constants.py    # Global configuration values
│   └── parsers.py      # Utilities for transforming API responses (e.g., HTML parsing)
├── __init__.py         # Package initialization file
├── __main__.py         # Script execution entry point
└── server.py           # Core MCP server logic implementation

Testing resources mirror this structure:

tests/
├── integration/        # Tests involving live external API interactions
├── models/             # Unit tests for data model validation
├── providers/          # Unit tests for individual registry connectors
└── utils/              # Tests for utility functions

Community Involvement

Contributions are welcomed to enhance the utility and breadth of mcp-package-registry-gateway. Whether adding support for new artifact sources, refining existing endpoint logic, or improving documentation, your input is valued.

Refer to existing MCP server implementations for architectural guidance: https://github.com/modelcontextprotocol/servers

Submissions via pull requests for features, fixes, or documentation improvements are highly appreciated.

Licensing Information

This software is released under the permissive MIT License. Users retain broad freedoms to employ, alter, and disseminate the code, contingent upon adherence to the conditions laid out in the project's LICENSE file.