mcp-lab — глобальный MCP‑сервер (Node.js + TypeScript)

Расширяемый MCP‑сервер со стандартным транспортом stdio для Cursor и плагинной архитектурой инструментов.

• Транспорт: stdio (совместим с Cursor)
• Инструменты из коробки:
  • health.ping — проверка доступности
  • fs.readText — безопасное чтение UTF‑8 файлов только внутри ALLOW_DIR
  • images.generate — генерация изображения через OpenAI (base64 PNG)

Требования

• Node.js 18+
• Cursor установлен

Установка

npm install
npm run build

Настройка в Cursor

1. Откройте: Tools & Integrations → MCP Tools → New MCP Server (откроется редактор JSON настроек MCP)
2. Добавьте/обновите конфиг (абсолютный путь к dist/server.js):

{
  "mcpServers": {
    "mcp-lab": {
      "command": "node",
      "args": [
        "C:/Users/Home/Desktop/projects/mcp-server/dist/server.js"
      ],
      "env": {
        "OPENAI_API_KEY": "${secrets:OPENAI_API_KEY}",
        "ALLOW_DIR": "${workspaceRoot}"
      }
    }
  }
}

3. В Settings → Secrets создайте секрет OPENAI_API_KEY (значение ключа OpenAI).

Примечания:

• После изменений в исходниках выполняйте npm run build, так как Cursor запускает dist/server.js.
• Значения из конфигурации Cursor имеют приоритет над значениями из .env проекта.

Переменные окружения

• OPENAI_API_KEY — ключ OpenAI (обязателен для images.generate)
• ALLOW_DIR — корень безопасности для файловых инструментов (по умолчанию ${workspaceRoot}). fs.readText может читать только внутри этого каталога.
• OPENAI_IMAGE_MODEL — модель изображений (по умолчанию dall-e-3)

Сервер также читает файл .env каждого проекта (через dotenv).

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

Откройте любой проект в Cursor — сервер активируется автоматически. В списке MCP Tools появятся инструменты mcp-lab.

Примеры вызовов (аргументы вводятся в окне инструмента):

• health.ping → без аргументов → ответ: pong
• fs.readText с телом { "relPath": "package.json" } → текст файла
• images.generate с телом { "prompt": "a simple blue circle", "size": "512x512" } → изображение (base64)

Пояснение параметров:

• fs.readText.relPath — относительный путь от ALLOW_DIR (по умолчанию это корень открытого проекта, ${workspaceRoot}). Допустимы прямые слэши (/) на любой ОС. Выход за пределы ALLOW_DIR (например, через ..) блокируется ошибкой: "Access denied: outside allowDir". Читает только текст в кодировке UTF‑8.

Расширение (добавление нового инструмента)

Создайте файл src/tools/my-tool.ts и экспортируйте регистратор:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

export function registerMyTool(server: McpServer) {
  server.registerTool(
    "my.doStuff",
    { title: "My Tool", description: "Does stuff", inputSchema: { id: z.string() } },
    async ({ id }) => ({ content: [{ type: "text", text: `ok:${id}` }] })
  );
}

Подключите в src/server.ts:

import { registerMyTool } from "./tools/my-tool.js";
registerMyTool(server);

Безопасность

• Удаляющих инструментов нет (delete/remove отсутствуют)
• Доступ к файловой системе только в границах ALLOW_DIR (вне — запрещено)
• Секреты не логируются; ключи передаются через Secrets/ENV

Отладка

• Если инструменты не видны: проверьте глобальный JSON настроек MCP, наличие OPENAI_API_KEY и перезапустите Cursor