npm-mcp

npm-mcp — это небольшой, предназначенный только для чтения сервер Model Context Protocol для публичного реестра npm. Он позволяет MCP-совместимым ИИ-клиентам обнаруживать npm-пакеты и просматривать целевые метаданные пакетов, не открывая возможностей установки, публикации, входа в систему, работы с оболочкой, файловой системой или произвольной загрузки.

Запуск с Docker

См. краткое руководство по Docker, чтобы запустить сервер и MCP Inspector из свежего клона. Основная команда:

docker compose --profile inspector up --build -d

Чтобы проверить использование MCP-инструментов под управлением модели без локального запуска модели, используйте LibreChat с маршрутизатором бесплатных моделей OpenRouter:

docker compose -f compose.yaml -f compose.openrouter.yaml --profile openrouter up --build -d

Затем откройте http://127.0.0.1:3080. Ключ API OpenRouter требуется даже для бесплатных моделей. Инструкции по настройке и использованию см. в OPENROUTER_QUICKSTART.md. Локальный профиль Ollama остаётся доступным в качестве опциональной полностью локальной альтернативы.

Related MCP server: @kongyo2/npm-info-mcp-server

Инструменты

Все инструменты возвращают JSON в виде текста для широкой совместимости с клиентами и предоставляют то же значение в виде структурированного содержимого MCP. Ответы по пакетам намеренно фильтруются, а не возвращают полный документ метаданных реестра.

Требования и установка

• Node.js 20 или новее (для встроенных fetch и AbortSignal.timeout)

• npm

git clone <repository-url>
cd npm-mcp
npm install

Локальный запуск

npm start

Процесс ожидает сообщения MCP на stdin и записывает ответы протокола в stdout. Не вводите данные в него интерактивно; его должен запускать MCP-клиент. Режим разработки с автоперезапуском доступен через npm run dev.

Развёртывание

Для локальных клиентов используйте точку входа stdio. Для развёртывания в Docker и облаке используйте stateless-точку входа Streamable HTTP по адресу /mcp; по умолчанию она требует bearer-токен и предоставляет /healthz для проверок работоспособности. Инструкции по Docker Compose и развёртыванию в Google Cloud Run, Azure Container Apps, AWS App Runner/ECS Fargate и Kubernetes см. в руководстве по развёртыванию в Docker и облаке.

Файл Compose также включает официальный MCP Inspector в качестве опционального клиента. Выполните docker compose --profile inspector up --build -d, затем откройте http://127.0.0.1:6274. Инструкции по настройке токена и использованию CLI см. в разделе Запуск MCP-клиента в Docker.

Тестирование

npm test

Тесты используют встроенный в Node.js test runner и имитированные ответы fetch, поэтому им не нужен живой реестр npm.

Чтобы интерактивно проверить сервер с помощью MCP Inspector:

npx @modelcontextprotocol/inspector node src/index.js

Откройте URL, напечатанный Inspector, подключитесь, выберите Инструменты, выберите инструмент, введите его аргументы и запустите его.

Конфигурация MCP-клиента

Используйте абсолютный путь, чтобы клиент мог запустить сервер из любого рабочего каталога:

{
  "mcpServers": {
    "npm": {
      "command": "node",
      "args": ["/absolute/path/to/npm-mcp/src/index.js"]
    }
  }
}

Точный внешний ключ конфигурации может отличаться в зависимости от MCP-клиента, но команда и аргументы одинаковы.

Примеры вызовов

{"name":"npm_search_packages","arguments":{"query":"postgres orm","limit":10}}

{"name":"npm_get_package","arguments":{"packageName":"@nestjs/core"}}

{"name":"npm_get_latest_version","arguments":{"packageName":"react"}}

{"name":"npm_get_versions","arguments":{"packageName":"axios"}}

Архитектура

• src/index.js отвечает только за запуск stdio.

• src/http.js и src/http-server.js предоставляют аутентифицированную точку входа Streamable HTTP, используемую контейнерами.

• src/server.js создаёт MCP-сервер и регистрирует четыре инструмента.

• src/tools/ содержит схемы, целевую обработку ответов и обработчики.

• src/services/npm-registry.js — единственный модуль, который взаимодействует с npm. Он проверяет имена пакетов, ограничивает URL-адреса официальными конечными точками реестра, применяет тайм-аут и нормализует ошибки сети/HTTP/ответов.

Scoped-имена кодируются как один сегмент пути реестра. Сервер не сохраняет состояние и не выполняет запись.

Возможные улучшения

Возможные будущие дополнения включают статистику загрузок, анализ зависимостей, информацию о безопасности пакетов, кэширование и удалённую аутентификацию на основе OAuth.