toy-mcp-server

Минимальный сервер Model Context Protocol (MCP), написанный с нуля, чтобы понять, как MCP работает на самом деле, — без генераторов шаблонного кода, без шаблонов, только SDK.

Это первый практический MCP-проект: два инструмента и один ресурс, подключённые к Claude Desktop через stdio.

Что он делает

MCP позволяет LLM-клиенту (например, Claude Desktop) вызывать функции, работающие на вашем компьютере, а не просто генерировать текст на основе обучающих данных. Этот сервер предоставляет:

Инструменты (функции, которые может вызывать Claude):

• roll_dice — бросает N кубиков с настраиваемым числом граней

• flip_coin — подбрасывает монету N раз

Ресурсы (данные только для чтения, которые Claude может получать):

• server-info — базовые метаданные о сервере (имя, назначение, время запуска)

Зачем это существует

LLM не имеют доступа ни к чему за пределами собственных обучающих данных и по умолчанию не могут ничего делать — они лишь генерируют текст. MCP — это стандартный способ дать модели:

• возможность, которой у неё нет самой по себе (например, настоящую случайность — LLM, как известно, сами плохо справляются с выбором случайных чисел)

• доступ к актуальным или приватным данным, о которых модель никак не может знать

Это маленькая безопасная песочница для этой идеи, прежде чем направлять MCP-сервер на что-то реальное (базу данных, API с авторизацией и т.д.).

Технологический стек

• TypeScript

• @modelcontextprotocol/sdk — официальный MCP SDK

• zod — проверка схемы аргументов инструментов во время выполнения

• transport stdio (локальное взаимодействие с Claude Desktop через дочерний процесс)

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

toy-mcp-server/
├── src/
│   └── index.ts       # server setup, tools, and resource
├── build/              # compiled output (git-ignored)
├── package.json
├── tsconfig.json
└── README.md

Установка

1. Установите зависимости

npm install

2. Сборка

npm run build

3. Подключение к Claude Desktop

Найдите файл конфигурации Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: обычно в %LOCALAPPDATA%\Packages\<Claude package folder>\LocalCache\Roaming\Claude\claude_desktop_config.json — точный путь зависит от способа установки (Microsoft Store или прямой установщик). Надёжный способ найти файл: откройте Claude Desktop → Настройки → Разработчик → Локальные MCP-серверы → Изменить конфигурацию — откроется именно тот файл, который читает приложение.

Добавьте этот сервер в раздел mcpServers (объедините с существующим файлом, а не перезаписывайте его):

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

Замените путь на реальный абсолютный путь к build/index.js на вашей машине. В Windows экранируйте обратные слэши (\\) в JSON-строке.

4. Перезапустите Claude Desktop

Полностью завершите работу приложения (не просто закройте окно) и откройте снова. Проверьте Настройки → Developer → Локальные MCP-серверы, чтобы убедиться, что toy-mcp-server отображается как подключённый.

5. Попробуйте

В чате спросите:

• "Брось 3 шестигранных кубика"

• "Подбрось монету 10 раз"

Над ответом вы увидите небольшой индикатор вызова инструмента (например, «Бросить Dice»), подтверждающий, что Claude действительно выполнил функцию, а не угадал ответ.

Как это работает, кратко

• McpServer — объект, который объявляет возможности сервера любому подключающемуся клиенту

• registerTool(name, config, handler) — регистрирует вызываемую функцию. config.inputSchema использует Zod для проверки любых аргументов, отправленных моделью, прежде чем выполнится обработчик

• registerResource(name, uri, config, handler) — регистрирует данные только для чтения, доступные по URI и получаемые без аргументов

• StdioServerTransport — формат обмена: Claude Desktop запускает этот файл как до ашний процесс и общается через stdin/stdout по JSON-RPC. Здесь console.log никогда не используется для логирования, потому что stdout — это настоящий канал протокола; вместо него используется console.error (stderr)

Что дальше

• Замените игрушечные инструменты на реальные, работающие с настоящей базой данных (Postgres через Prisma)

• Добавьте инструмент на базе GitHub (например, list_open_prs), чтобы попрактиковаться в авторизации по токенам

• Изучите transport Streamable HTTP, чтобы размещать этот сервер удалённо, а не локально

Лицензия

MIT