MCP Contract Server

MCP (Model Context Protocol) сервер для предоставления API контракта integ-api в Cursor при разработке integ-admin.

Обзор

MCP сервер работает как standalone приложение и предоставляет инструменты для работы с API контрактом:

• Получение списка эндпоинтов
• Детали эндпоинтов с параметрами и responses
• Схемы DTO с валидацией
• Поиск по API
• Генерация Angular сервисов
• Исходный код DTO классов

Архитектура

integ-api/
├── contract/
│   └── openapi.json         # Генерируется скриптом
├── mcp/
│   ├── src/
│   │   └── server.ts        # MCP сервер
│   ├── dist/                # Сборка
│   ├── package.json
│   └── tsconfig.json
└── scripts/
    └── generate-contract.ts # Генерация OpenAPI

Установка

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

# Основные зависимости
npm install

# MCP сервер
cd mcp && npm install && cd ..

2. Генерация контракта

npm run generate:contract

Скрипт:

• Запускает NestJS приложение в headless режиме
• Извлекает OpenAPI документ через SwaggerModule
• Сохраняет в contract/openapi.json

3. Запуск MCP сервера

Dev режим (с hot reload):

npm run mcp:dev

Production режим:

npm run mcp:build
npm run mcp:start

npm Scripts

Команда	Описание
npm run generate:contract	Генерирует OpenAPI spec
npm run mcp:dev	Запускает MCP сервер в dev режиме
npm run mcp:build	Собирает MCP сервер для production
npm run mcp:start	Запускает собранный MCP сервер

Доступные инструменты

get_endpoints

Получить список всех API эндпоинтов с методами, описанием и тегами.

Параметры:

• tag (optional) - Фильтр по тегу

Пример:

{
	"tag": "integrations"
}

get_endpoint_details

Получить полную информацию об эндпоинте: параметры, body, responses.

Параметры:

• path - Путь эндпоинта (например /api/integrations)
• method - HTTP метод (GET, POST, PUT, PATCH, DELETE)

Пример:

{
	"path": "/api/integrations",
	"method": "GET"
}

get_schema

Получить схему DTO/Entity с типами и валидацией.

Параметры:

• name - Имя схемы (например CreateHandlerDto)

Пример:

{
	"name": "CreateHandlerDto"
}

list_schemas

Получить список всех DTO и Entity схем.

Параметры:

• filter (optional) - Фильтр по имени

Пример:

{
	"filter": "dto"
}

search_api

Поиск эндпоинтов и схем по ключевым словам.

Параметры:

• query - Поисковый запрос

Пример:

{
	"query": "integration"
}

generate_angular_service

Сгенерировать пример Angular сервиса для эндпоинта.

Параметры:

• path - Путь эндпоинта
• method - HTTP метод

Пример:

{
	"path": "/api/integrations",
	"method": "GET"
}

get_dto_source

Получить исходный код DTO класса с декораторами валидации.

Параметры:

• name - Имя DTO класса

Пример:

{
	"name": "CreateHandlerDto"
}

Интеграция в Cursor

Конфигурация в integ-admin

Создайте файл .cursor/mcp.json в проекте integ-admin:

Dev режим:

{
	"mcpServers": {
		"integ-api": {
			"command": "npx",
			"args": ["tsx", "/absolute/path/to/integ-api/mcp/src/server.ts"]
		}
	}
}

Production режим:

{
	"mcpServers": {
		"integ-api": {
			"command": "node",
			"args": ["/absolute/path/to/integ-api/mcp/dist/server.js"]
		}
	}
}

TIP

Замените /absolute/path/to/integ-api на реальный путь к проекту integ-api на вашей машине.

Рабочий процесс

При изменении API

1. Внесите изменения в контроллеры/DTO в integ-api
2. Перегенерируйте контракт:

npm run generate:contract

3. MCP сервер автоматически перезагрузится (в dev режиме)

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

После настройки .cursor/mcp.json в integ-admin, инструменты MCP доступны в Cursor:

1. Cursor автоматически подключается к MCP серверу
2. Инструменты доступны для генерации кода и получения информации об API
3. Используйте tools для быстрого создания Angular сервисов

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

mcp/
├── src/
│   └── server.ts          # Основной MCP сервер с 7 tools
├── dist/                   # Скомпилированный код
├── package.json            # Зависимости
├── tsconfig.json           # TypeScript конфигурация
├── .gitignore
└── README.md

Важные моменты

Существующий McpModule

Модуль src/app/shared/modules/mcp/ остается без изменений - он предназначен для runtime работы с интеграциями, не для предоставления контракта.

Обновление контракта

При каждом изменении API необходимо перегенерировать контракт командой npm run generate:contract.

Директория contract/

Содержимое contract/ игнорируется в git - это сгенерированные артефакты.

Troubleshooting

MCP сервер не запускается

# Проверить что контракт сгенерирован
ls contract/openapi.json

# Если нет - сгенерировать
npm run generate:contract

# Проверить зависимости MCP
cd mcp && npm install

Cursor не видит инструменты

1. Проверьте путь в .cursor/mcp.json
2. Перезапустите Cursor
3. Проверьте логи MCP сервера

Ошибки генерации контракта

# Проверить что приложение запускается
npm start

# Проверить типы
npm run typecheck

# Проверить зависимости
npm install

См. также

• Git Workflow - Процесс разработки
• Правила кода - Стандарты кодирования
• Архитектура - Структура проекта