NPM Registry и публикация

Руководство по публикации MCP серверов в NPM Registry и официальный MCP Registry

Публикация MCP серверов в NPM Registry позволяет легко распространять и устанавливать серверы через npm/npx.

Подготовка пакета

package.json

{
  "name": "@myorg/mcp-server-example",
  "version": "1.0.0",
  "description": "MCP сервер для примера",
  "type": "module",
  "main": "dist/index.js",
  "bin": {
    "mcp-server-example": "./dist/index.js"
  },
  "files": [
    "dist",
    "README.md"
  ],
  "scripts": {
    "build": "tsc",
    "prepare": "npm run build"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "@types/node": "^20.0.0"
  },
  "keywords": [
    "mcp",
    "model-context-protocol",
    "ai",
    "claude"
  ],
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/myorg/mcp-server-example.git"
  },
  "mcpName": "example"
}

Важные поля

Поле	Описание
`name`	Уникальное имя пакета (рекомендуется с scope `@org/`)
`bin`	Путь к исполняемому файлу
`files`	Файлы для включения в пакет
`mcpName`	Имя для MCP Registry (опционально)

Структура проекта

mcp-server-example/
├── src/
│   ├── index.ts
│   └── tools/
├── dist/              # Скомпилированный код
├── package.json
├── tsconfig.json
├── README.md
└── LICENSE

src/index.ts

#!/usr/bin/env node

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new McpServer({
  name: "example",
  version: "1.0.0",
});

// Регистрация инструментов
server.tool("hello", {}, async () => ({
  content: [{ type: "text", text: "Hello from MCP!" }],
}));

// Запуск
const transport = new StdioServerTransport();
await server.connect(transport);

Публикация в NPM

Регистрация на npmjs.com

npm adduser

Проверка перед публикацией

# Что будет опубликовано
npm pack --dry-run

# Линтинг
npm run lint

# Тесты
npm test

# Сборка
npm run build

Публикация

# Первая публикация
npm publish --access public

# Обновление версии
npm version patch  # 1.0.0 -> 1.0.1
npm version minor  # 1.0.0 -> 1.1.0
npm version major  # 1.0.0 -> 2.0.0

# Публикация обновления
npm publish

Scoped packages

# Публичный scoped пакет
npm publish --access public

# Приватный (требует платную подписку)
npm publish

MCP Registry

MCP Registry — официальный реестр MCP серверов, который агрегирует метаданные из NPM, PyPI и других источников.

Добавление в MCP Registry

Убедитесь, что mcpName указан в package.json:

{
  "mcpName": "example"
}

Пакет должен быть опубликован в NPM
Регистрация в MCP Registry:

# Установка CLI
npm install -g @modelcontextprotocol/registry-cli

# Аутентификация
mcp-registry login

# Публикация
mcp-registry publish

server.json

Альтернативный способ — создать server.json:

{
  "name": "example",
  "description": "Пример MCP сервера",
  "version": "1.0.0",
  "homepage": "https://github.com/myorg/mcp-server-example",
  "license": "MIT",
  "author": {
    "name": "My Organization"
  },
  "categories": ["tools", "utilities"],
  "runtime": {
    "type": "npm",
    "package": "@myorg/mcp-server-example"
  }
}

Использование опубликованного сервера

Через npx

npx -y @myorg/mcp-server-example

Claude Desktop конфигурация

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@myorg/mcp-server-example"]
    }
  }
}

Глобальная установка

npm install -g @myorg/mcp-server-example

{
  "mcpServers": {
    "example": {
      "command": "mcp-server-example"
    }
  }
}

Private NPM Registry

Конфигурация .npmrc

# .npmrc
@myorg:registry=https://npm.mycompany.com
//npm.mycompany.com/:_authToken=${NPM_TOKEN}

Публикация в приватный registry

npm publish --registry https://npm.mycompany.com

Использование

{
  "mcpServers": {
    "private-server": {
      "command": "npx",
      "args": [
        "--registry", "https://npm.mycompany.com",
        "-y", "@myorg/private-mcp-server"
      ]
    }
  }
}

Версионирование

Semantic Versioning

MAJOR (1.0.0 → 2.0.0): Несовместимые изменения API
MINOR (1.0.0 → 1.1.0): Новые функции, обратная совместимость
PATCH (1.0.0 → 1.0.1): Исправления багов

Pre-release версии

npm version prerelease --preid=beta  # 1.0.0 -> 1.0.1-beta.0
npm publish --tag beta

Использование beta версий

npx -y @myorg/mcp-server-example@beta

CI/CD публикация

GitHub Actions

# .github/workflows/publish.yml
name: Publish to NPM

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'

      - run: npm ci
      - run: npm run build
      - run: npm test

      - run: npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Получение NPM_TOKEN

Зайдите на npmjs.com
Settings → Access Tokens → Generate New Token
Выберите “Automation” тип
Добавьте в GitHub Secrets

README для NPM

# @myorg/mcp-server-example

MCP сервер для примера.

## Установка

\`\`\`bash
npx -y @myorg/mcp-server-example
\`\`\`

## Конфигурация Claude Desktop

\`\`\`json
{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@myorg/mcp-server-example"]
    }
  }
}
\`\`\`

## Инструменты

- `hello` - Приветственное сообщение
- `add` - Сложение чисел

## Лицензия

MIT