blockmine-mcp

English | Русский

Model Context Protocol мост и setup-визард для BlockMine. Сам MCP-сервер встроен в BlockMine — этот npm-пакет нужен как тонкий клиент для AI-приложений, которые умеют только stdio (Claude Desktop, старые Cursor/Cline).

Архитектура

                            Authorization: Bearer pk_...
  AI клиент ───HTTP MCP─────────────────────────────────► BlockMine /api/mcp
  (Claude Code, Cursor, Cline,
   Claude Desktop, ...)

           или, для stdio-only клиентов:

  AI клиент ─stdio─► blockmine-mcp (npm) ──HTTP MCP──► BlockMine /api/mcp

MCP endpoint — часть самого BlockMine. Авторизация — обычным Panel API Key. Можно подключаться с любого хоста, лишь бы BlockMine был доступен.

Быстрый старт

npx blockmine-mcp setup

Визард сам:

1. спросит URL BlockMine (по умолчанию http://localhost:3001),
2. подскажет где создать pk_... ключ,
3. проверит токен,
4. зарегистрирует сервер в выбранном AI-клиенте (Claude Code через CLI, Claude Desktop через конфиг-файл, либо просто напечатает сниппет).

Перезапусти AI-клиент — готово.

Установка вручную

Нативный HTTP (рекомендуется)

Для клиентов которые умеют HTTP MCP — Claude Code, свежие Cursor и Claude Desktop:

Claude Code (CLI):

claude mcp add --scope user --transport http blockmine \
  http://localhost:3001/api/mcp \
  --header "Authorization: Bearer pk_твой_ключ"

Через конфиг-файл:

{
  "mcpServers": {
    "blockmine": {
      "type": "http",
      "url": "http://localhost:3001/api/mcp",
      "headers": { "Authorization": "Bearer pk_твой_ключ" }
    }
  }
}

Fallback на stdio (через этот пакет)

Для старых клиентов которые умеют только stdio (некоторые сборки Cline, Zed):

{
  "mcpServers": {
    "blockmine": {
      "command": "npx",
      "args": ["-y", "blockmine-mcp"],
      "env": {
        "BLOCKMINE_URL": "http://localhost:3001",
        "BLOCKMINE_API_TOKEN": "pk_твой_ключ"
      }
    }
  }
}

Требования

• Node.js 18+.
• Запущенный BlockMine, доступный по HTTP.
• Panel API Key (pk_...) из BlockMine → Настройки → API ключи.

Переменные окружения (для proxy-режима)

| Переменная | По умолчанию | Назначение | | --- | --- | --- | | BLOCKMINE_URL | http://localhost:3001 | Базовый URL панели. | | BLOCKMINE_API_TOKEN | (обязательно) | Panel API Key. | | BLOCKMINE_API_TIMEOUT_MS | 30000 | Таймаут запроса. |

Tools которые отдаёт BlockMine MCP

Жизненный цикл ботов: list_bots, get_bot, get_bot_states, start_bot, stop_bot, restart_bot, send_message_to_bot, get_bot_logs

Плагины: get_bot_plugins, get_plugin_settings, get_plugin_store, update_plugin_settings, enable_disable_plugin, install_local_plugin

Управление: get_bot_users, get_user_info, get_bot_groups, get_bot_permissions, get_bot_commands

Права проверяются per-tool теми же scope'ами что и обычное API панели (bot:start_stop, plugin:settings:edit, management:view и т.д.). Какие tools доступны — зависит от роли ключа.

Решение проблем

Cannot reach BlockMine at ... — панель оффлайн или неверный URL. Запусти BlockMine и перезапусти setup.

401 / токен не авторизуется — ключ неверный, просрочен или отозван. Сгенерируй новый и снова setup.

403 / permission denied — у токена нет нужного scope. Поправь роль в панели или используй ключ с более широкими правами.

Лицензия

MIT — см. LICENSE.