MCP Server Pacman

🚀 MCP Server Pacman

MCP Server Pacman is a service that integrates multiple package registry interfaces, providing users with a unified way to query and manage packages from different sources such as PyPI, npm, crates.io, Docker Hub, and Terraform Registry.

🚀 Quick Start

To quickly get started with MCP Server Pacman, you can install it via pip and start the service with default settings.

pip install mcp-server-pacman
mcp-server-pacman --port=4001

✨ Features

Data Provider Interfaces

• PyPI: Offers Python package information query functionality.
• npm: Supports npm package search and detailed information retrieval.
• crates.io: Integrates the Rust language package registry.
• Docker Hub: Provides Docker image indexing services.
• Terraform Registry: Supports Terraform module queries.

Caching Mechanism

• By default, it uses in-memory caching, and can be extended to support Redis or other storage solutions.

Logging

• It has a built - in logging system that outputs to the console by default.
• You can configure file logging and log rotation policies.

📦 Installation

System Requirements

• Operating System: Linux, macOS, Windows (Linux environment is recommended).
• Python Version: Python 3.6 or higher.
• Dependency Management: It is recommended to use pip for package management.

Installation Methods

Method 1: Install from Source Code

1. Clone the repository

   git clone https://github.com/yourusername/mcp-server-pacman.git
   cd mcp-server-pacman
   

2. Install dependencies
   • Run the following command in the project root directory to install all dependencies:

     pip install -r requirements.txt
     

3. Configure environment variables (optional)
   • Set environment variables as needed, such as MCP_SERVER_PORT and LOG_LEVEL. For example:

     export MCP_SERVER_PORT=4001
     export LOG_LEVEL=DEBUG
     

4. Start the service

   python -m mcp_server.app
   

Method 2: Install using pip

1. Install the package

   pip install mcp-server-pacman
   

2. Start the service

   mcp-server-run
   

Configuration Instructions

• Configuration File: The main configuration file of the project is located at config/settings.py. You can modify the settings in this file as needed.
• Environment Variables: Some configurations can be overridden by environment variables. Please refer to Environment Variable Reference for details.

💻 Usage Examples

Query PyPI Package Information

# Search for packages
curl -X POST http://localhost:4001/pypi/search \
-d '{"query": "requests"}'

# Get package details
curl http://localhost:4001/pypi/package/requests

Query npm Packages

# Search for npm packages
curl -X POST http://localhost:4001/npm/search \
-d '{"query": "@vue/core"}'

# Get package download volume
curl http://localhost:4001/npm/downloads/@vue/core

📚 Documentation

Project Structure

Code Directory Structure

src/mcp_server_pacman/
├── models/             # Data model definitions
├── providers/          # Third - party service interface implementations
│   ├── pypi.py         # PyPI interface methods
│   ├── npm.py          # npm interface methods
│   ├── crates.py       # crates.io interface methods
│   ├── dockerhub.py    # Docker Hub interface methods
│   └── terraform.py    # Terraform Registry interface methods
├── utils/              # Utility function collection
│   ├── cache.py        # Cache - related functions
│   ├── constants.py    # Global constant definitions
│   └── parsers.py      # HTML parsing tools
├── __init__.py         # Package initialization file
├── __main__.py         # Program entry point
└── server.py           # MCP server implementation

Test Directory Structure

tests/
├── integration/        # Integration test cases (call real APIs)
├── models/             # Data model validation tests
├── providers/          # Provider interface function tests
└── utils/              # Utility function tests

Development Guide

Environment Setup

1. Clone the repository

   git clone https://github.com/yourusername/mcp-server-pacman.git
   cd mcp-server-pacman
   

2. Install dependencies

   pip install -r requirements.txt
   

Run Tests

# Run unit tests
pytest tests/unit/

# Run integration tests
pytest tests/integration/

Code Format Check

black .
flake8 .

API Documentation

Interface Overview

• Base URL: All API requests are sent to http://localhost:4001/api/.
• Supported HTTP Methods: GET, POST, PUT, DELETE.

Public API Endpoints

• /ping: Check if the service is alive. Method: GET. Response: pong.
• /health: Get the service health status. Method: GET. Response:

{
  "status": "ok",
  "timestamp": "2023-10-05T14:30:00Z"
}

Provider Interfaces

• /packages/pypi/search?q={query}: Search for PyPI packages. Method: GET. Parameters: query (required), the search keyword. Response: Returns a list of matching packages, including package names and version information.
• /packages/npm/versions/{package_name}: Get the version information of an npm package. Method: GET. Path parameters: package_name (required), the name of the npm package to be queried. Response: Returns a list of all available versions of the package.

Subscription and Notification

• /subscriptions/webhook: Add or delete webhook notification subscriptions. Method: POST, DELETE. Request body:

{
  "url": "http://example.com/webhook",
  "secret": "your-secret-token"
}

Response: Status code 200 OK, returns the subscription ID.

Error Handling

• Error Codes:
  • 400 Bad Request: Request parameters are incorrect or missing.
  • 401 Unauthorized: Authentication failed.
  • 503 Service Unavailable: The provider service is unavailable.
• Custom Error Response:

{
  "error": {
    "code": 400,
    "message": "Missing required query parameter."
  }
}

🔧 Technical Details

Core Components

• Configuration Management: settings.py contains all configuration parameters, such as port number, cache type, etc.
• Provider Interfaces:
  • pypi.py: Implements the interaction with PyPI, including search and package information query.
  • npm.py: Implements the interaction with the npm registry, including search and package version management.

Development Process

• Code Development:
  1. Create a feature module:

     touch providers/your_provider.py
     

  2. Write the implementation logic following the existing code style.
  3. After completion, submit it to the repository and ensure that all test cases pass.
• Test Development:
  1. Write unit tests when adding new features.

     pytest tests/test_your_provider.py -v
     

  2. Ensure that the test coverage meets the requirements (e.g., 80%).
  3. Run tests regularly to ensure code quality.

Packaging and Release

• Packaging Steps:
  1. Create a setup.py file:

     from setuptools import setup, find_packages
     
     setup(
         name="mcp-server-pacman",
         version="0.1",
         packages=find_packages(),
         install_requires=[
             "requests>=2.25.1",
             "gunicorn>=19.9.0"
         ],
     )
     

  2. Package:

     python setup.py sdist bdist_wheel
     

  3. Upload to a private repository or PyPI.

📄 License

This project is open - sourced under the MIT License:

MIT License

Copyright (c) [Year] [Copyright Holder]

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

📋 Frequently Asked Questions

Installation and Configuration

• Q: How to install the MCP server? A: You can install it via pip:

  pip install mcp-server-pacman
  

  Or install from source code and run setup.py.
• Q: How to configure the MCP server? A: Create a config/settings.py file and set the required parameters, such as the port number. Then start the service.

Usage and Operation

• Q: How to test the MCP service? A: You can use the curl command to send requests to the API endpoints:

  curl http://localhost:4001/api/ping
  

• Q: How to view the logs? A: Use the access logs and error logs provided by Gunicorn, or configure a log collection tool.

Performance and Scalability

• Q: What if the service response is slow? A: Check the Gunicorn configuration, increase the number of worker processes, or optimize the timeout settings of the provider interfaces.
• Q: How to horizontally scale the service? A: Use a reverse proxy (such as Nginx) to distribute requests to multiple MCP instances.

Troubleshooting

• Q: What if the service fails to start? A: Check the log file to find the error information and look for solutions in the problem - solving section.
• Q: How to update the MCP server? A: Stop the current service, pull the latest code, reinstall the dependencies, and restart the service.

Security and Permissions

• Q: How to enable authentication? A: Configure the basic authentication or JWT authentication module of the API to ensure that only authorized users can access the resources.
• Q: How to handle sensitive data? A: Use environment variables to store sensitive information and avoid storing passwords or other confidential data in plain text in the code.

📈 Upgrade Guide

Version Upgrade Steps

1. Stop the current service:
   • Use systemctl stop mcp-server or a similar command to stop the running service.
2. Update dependencies:
   • If installed from source code, pull the latest code.
   • Execute pip install --upgrade mcp-server-pacman to update to the new version.
3. Re - configure the service (if there are changes):
   • Check if the configuration files in the config directory have been updated or changed.
4. Restart the service:
   • Use systemctl start mcp-server to start the service and ensure that the upgrade is completed.
5. Verify the upgrade result:
   • Send requests to the API endpoints to confirm that the service responds normally and there are no functional abnormalities.

Precautions

• Backup Data: Back up all important data and configuration files before upgrading.
• Check the Change Log: Check the changelog of the new version to understand the new or modified functions and potential problems.
• Monitor the Service Status: Closely monitor the service operation after upgrading and handle any possible problems in a timely manner.

Common Upgrade Problems

• Q: An error occurs when starting the new version of the service? A: Check if there are any changes in the configuration files and ensure that all configuration items are correct. View the latest log file for more information.
• Q: Unable to connect to the database? A: Ensure that the database service is running normally and that the configuration information is compatible with the new version.

Contact Support

If you encounter problems during the upgrade process, please contact our technical support team:

• Email: support@mcp-server.com
• Phone: +1 - 800 - MCP - SERVER

🌐 Environment Variable Reference

Variable List

• Basic Configuration:
  • MCP_SERVER_PORT: The port number that the service listens on, default is 4001.
  • MCP_SERVER_ENV: The running environment, optional values are dev, prod, etc.
• Provider Interface Configuration:
  • PYPI_API_KEY: The API Key for authorized access to PyPI.
  • NPM_REGISTRY_URL: The URL of the custom npm package repository.
• Authentication and Authorization:
  • MCP_SERVER_AUTH_ENABLED: Whether to enable the authentication function, a boolean value, default is False.
  • JWT_SECRET_KEY: The secret key of the JWT token, used for signing and verification.
• Logging Configuration:
  • LOG_LEVEL: The log level, optional values are DEBUG, INFO, WARNING, ERROR, CRITICAL, default is INFO.
  • LOG_FILE_PATH: The save path of the log file. If not set, it will output to the standard output.

Usage Example

Before starting the service, set the environment variables:

export MCP_SERVER_PORT=4001
export LOG_LEVEL=DEBUG

Then run the service:

python -m mcp_server.app

🤝 Contribution Guide

How to Contribute Code

1. Fork the project repository: Fork the MCP server repository on GitHub.
2. Create a feature branch: Create an independent branch for each new feature or fix, such as feature/new-endpoint or bugfix/logging-issue.
3. Submit code: When submitting code, ensure that the commit message is clear and follows the project - specified format.
4. Open a Pull Request: Push your branch to the forked repository and initiate a Pull Request to the main repository.

How to Report Issues

1. Visit the project's GitHub repository.
2. Click the "Issues" tab to check if there are any existing issues.
3. If no relevant issues are found, click "New Issue" to create a new issue description.
4. Provide detailed information, including reproduction steps, error logs, etc.

How to Write Documentation

1. Modify the Markdown documentation files in the project, such as README.md, API_DOC.md, etc.
2. Keep the documentation clear and accurate, and ensure that it is consistent with the code implementation.
3. When submitting documentation modifications, indicate the updated content of the documentation in the Pull Request.

Contribution Guidelines

• Follow the code specification: Write new code according to the code style in the project and perform a format check before submission.
• Unit tests: Each feature branch should include corresponding unit tests to ensure code quality.
• Document synchronization: Update the relevant documentation content when modifying the code to maintain consistency.

Contributor List

Thank the following developers who have contributed to the MCP server:

• [Contributor Name] - Feature X and Fix Y
• [Another Contributor Name] - Added new feature Z