MCPController

MCPController — это однопользовательское MCP-приложение для управления врачами. ChatGPT подключается через OAuth 2.1 с PKCE, администратор входит в систему, выбирает, какие разрешения для врачей предоставить, а MCP-сервер предоставляет инструменты для работы с врачами на основе MongoDB.

Архитектура

ChatGPT
  ↓
OAuth
  ↓
Admin Login
  ↓
Admin Consent
  ↓
Granted Permissions
  ↓
MCP Access Token
  ↓
MCP /mcp
  ↓
Permission Check
  ↓
Doctor Tools
  ↓
MongoDB

Related MCP server: aster-mcd-mcp-adapter

Что делает это приложение

• Один администратор владеет всей системой.

• Нет публичной регистрации и переключения между несколькими пользователями.

• Администратор аутентифицируется с помощью учетных данных из переменных окружения.

• Экран согласия позволяет администратору одобрить doctor:read, doctor:write и doctor:delete.

• MCP-сервер проверяет одобренные области (scopes) при каждом вызове инструмента.

• Данные о врачах хранятся в MongoDB через простую модель Mongoose.

Аутентификация

Сессия браузера отделена от MCP-токена.

• Сессия браузера: HTTP-only cookie, используемая для интерфейса администратора и экрана согласия.

• MCP-токен доступа: Bearer-токен, используемый ChatGPT для обращения к /mcp.

• OAuth использует поток авторизационного кода с PKCE.

• Авторизационные коды одноразовые и недолговечные.

• Токены доступа и обновления хэшируются перед хранением.

Вход администратора использует ADMIN_EMAIL и ADMIN_PASSWORD из .env.

Управление врачами

Доменная модель намеренно небольшая:

• name — обязательная строка

• specialization — обязательная строка

• createdAt / updatedAt — управляются временными метками Mongoose

CRUD для врачей реализован в сервисном слое и используется как REST API администратора, так и слоем MCP-инструментов.

OAuth-поток

1. ChatGPT открывает конечную точку авторизации.

2. Если администратор не аутентифицирован, браузер переходит на /login.

3. Администратор входит в систему.

4. Страница согласия показывает запрошенные разрешения для врачей.

5. Администратор одобряет подмножество или отклоняет запрос.

6. Авторизационный код обменивается на токен доступа.

7. ChatGPT использует этот токен на /mcp.

Поток разрешений

Запрошенные области (scopes) сопоставляются с MCP-инструментами следующим образом:

• doctor:read → list_doctors, get_doctor

• doctor:write → add_doctor, update_doctor

• doctor:delete → delete_doctor

Бэкенд применяет разрешения дважды:

• OAuth записывает только одобренные области в авторизационный код и токен.

• Каждый MCP-инструмент проверяет области токена перед обращением к MongoDB.

MCP-инструменты

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

Используйте корневой файл .env. Приложение загружает его из корня проекта.

Обязательные значения для локального npm run dev (Vite на 5173, API на 3000):

NODE_ENV=development
PORT=3000
APP_URL=http://localhost:5173
API_URL=http://localhost:3000
MONGODB_URI=mongodb://127.0.0.1:27017/mcpcontroller
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=change-this-password
JWT_SECRET=change-this-to-a-long-random-secret
MCP_SERVER_NAME=MCPController
MCP_SERVER_VERSION=1.0.0

Код также поддерживает переменные времени жизни токенов/сессий с безопасными значениями по умолчанию:

• JWT_EXPIRES_IN

• AUTH_CODE_TTL_SECONDS

• ACCESS_TOKEN_TTL_SECONDS

• REFRESH_TOKEN_TTL_SECONDS

На Vercel APP_URL и API_URL должны быть публичным HTTPS-источником (см. раздел «Развертывание» ниже).

Локальная настройка

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

npm install

2. Запустите MongoDB локально.

3. Заполните примерными данными:

npm run seed

4. Запустите приложение:

npm run dev

В режиме разработки React-клиент работает через Vite и проксирует API-запросы на бэкенд.

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

Запустите автоматические проверки с помощью:

npm test

Запустите сборку клиента с помощью:

npm run build

Текущий набор тестов покрывает:

• вход администратора

• отключенную регистрацию

• модель врача и CRUD-сервис

• одобрение областей OAuth

• проверку разрешений MCP-инструментов

• отзыв токенов

Подключение ChatGPT

Используйте URL авторизации, предоставляемый сервером:

• /.well-known/oauth-authorization-server

• /.well-known/oauth-protected-resource

• /oauth/token

• /mcp

Типичный поток:

1. ChatGPT обнаруживает метаданные OAuth.

2. ChatGPT запрашивает авторизацию для MCP-ресурса.

3. Браузер перенаправляет на экран входа администратора.

4. Администратор просматривает разрешения и нажимает Allow & Connect.

5. ChatGPT обменивает код на токены.

6. ChatGPT вызывает MCP-инструменты, используя Bearer-токен.

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

Приложение — единый источник: Express обслуживает /api, /oauth, /mcp, обнаружение OAuth и сборку React.

Vercel

В этом репозитории уже есть vercel.json и api/index.js. Vercel запускает Express-приложение как одну serverless-функцию и перенаправляет все пути на нее.

1. MongoDB Atlas

1. Создайте кластер (бесплатного M0 достаточно).

2. Создайте пользователя базы данных.

3. Сетевой доступ: разрешите 0.0.0.0/0, чтобы Vercel мог подключиться (или добавьте IP-адреса Vercel, если предпочитаете).

4. Скопируйте строку подключения, например:

mongodb+srv://USER:PASSWORD@cluster0.xxxxx.mongodb.net/mcpcontroller?retryWrites=true&w=majority

2. Разверните проект

• Загрузите этот репозиторий на GitHub.

• В Vercel импортируйте репозиторий.

• Framework Preset: Other (оставьте). vercel.json задает установку и сборку.

• Root Directory: оставьте корень репозитория (не устанавливайте client или server).

• Версия Node.js: 20.x или новее.

3. Переменные окружения в Vercel

Project → Settings → Environment Variables. Установите их для Production (и для Preview, если используете preview-URL).

Не помещайте ADMIN_PASSWORD или JWT_SECRET в React-приложение. Клиент общается только с /api.

Если позже добавите собственный домен, измените APP_URL и API_URL на https://your-domain.com и переразверните.

Сгенерируйте JWT_SECRET с помощью:

node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"

4. Первое развертывание и заполнение данных

1. Разверните.

2. Откройте https://your-app.vercel.app/api/health — вы должны увидеть { "ok": true, ... }.

3. Заполните MongoDB со своей машины, указав Atlas (не serverless-функцию Vercel):

# In the project root, temporarily set MONGODB_URI to the Atlas URI in .env
npm run seed

Скрипт заполнения создает строку администратора, примерных врачей и локальный клиент MCP Inspector. После этого войдите на живой сайт с ADMIN_EMAIL / ADMIN_PASSWORD.

5. Подключение ChatGPT

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

• https://your-app.vercel.app/.well-known/oauth-authorization-server

• https://your-app.vercel.app/.well-known/oauth-protected-resource

• https://your-app.vercel.app/mcp

В ChatGPT (или MCP Inspector) добавьте этот MCP-URL. ChatGPT откроет экраны входа и согласия на том же домене, затем вызовет /mcp с Bearer-токеном.

CLI-развертывание (необязательно)

npm i -g vercel
vercel login
vercel env pull   # optional: sync env locally
vercel --prod

После первого продакшн-развертывания скопируйте URL в APP_URL и API_URL, если использовали заполнитель, затем переразверните, чтобы метаданные OAuth указывали на реальный источник.

Замечания по безопасности

• Не раскрывайте ADMIN_PASSWORD или JWT_SECRET браузеру.

• Храните OAuth-токены в базе данных в хэшированном виде.

• Одобряйте только те области, которые администратор действительно хочет предоставить ChatGPT.

• Отзывайте доступ, когда соединение больше не должно быть доверенным.

• Вход администратора существует только для авторизации ChatGPT и управления данными врачей; публичного потока регистрации нет.

Данные для заполнения

Скрипт заполнения создает:

• примерных врачей

• примерный OAuth-клиент для локального использования в Inspector

Он не создает демо-пользователей и не задает учетные данные администратора.