459 lines
23 KiB
Markdown
459 lines
23 KiB
Markdown
# FAQ: Полезно ли ИИ обращаться к MCP серверу, который отвечает только `quack`
|
||
|
||
Вот почему это технически полезно для основной модели:
|
||
|
||
## 1. Фиксация «Контекстного окна»
|
||
|
||
Когда ИИ вызывает инструмент (tool call), он обязан сформулировать аргументы.
|
||
|
||
- **Механика**: Чтобы получить `кряк` из MCP, модели придется выгрузить свои промежуточные мысли из весов (внутреннего состояния) в текст (входящий контекст).
|
||
- **Польза**: Это превращает неявные рассуждения в явные данные. При генерации следующего токена модель будет видеть свое собственное объяснение как уже случившийся факт, на который можно опираться.
|
||
|
||
## 2. Принудительное замедление (Compute-over-time)
|
||
|
||
ИИ часто «проскакивает» сложные моменты, пытаясь выдать ответ слишком быстро.
|
||
|
||
- **Механика**: Вызов MCP-инструмента прерывает процесс прямой генерации ответа.
|
||
- **Польза**: Это заставляет модель сделать паузу и структурировать задачу. Это фактически «взлом» логики, заставляющий модель использовать больше токенов на рассуждение, что почти всегда повышает качество решения.
|
||
|
||
## 3. Эффект «Внешней памяти»
|
||
|
||
Если задача огромная, ИИ может начать «забывать» детали начала условия.
|
||
|
||
- **Польза**: Записывая статус в «уточку», модель создает для самой себя краткое резюме (summary) пройденных этапов.
|
||
|
||
## Как это описать в описании MCP-сервера:
|
||
|
||
Вы можете описать это как «Explicit Reasoning Buffer» (Буфер явных рассуждений).
|
||
|
||
- **Для кого**: Для сложных агентов, которые склонны к логическим циклам или галлюцинациям.
|
||
- **Суть**: Инструмент предоставляет модели безопасное пространство для «проговаривания» плана действий перед тем, как трогать реальные файлы или базу данных.
|
||
|
||
---
|
||
|
||
Чтобы сделать свой Model Context Protocol (MCP) сервер, вам нужно реализовать приложение, которое общается с клиентом (например, Claude Desktop, Cursor или ИИ-агентом) через JSON-RPC 2.0. Протокол стандартизирован компанией Anthropic и работает поверх стандартных потоков ввода-вывода (Stdio) или WebSockets. [1, 2]
|
||
|
||
---
|
||
|
||
## Какое API у MCP сервера?
|
||
|
||
API MCP-сервера базируется на трех китах (примитивах), которые сервер «обнажает» для ИИ-модели: [3]
|
||
|
||
1. **Tools (Инструменты)** — функции, которые ИИ может вызывать (например, запустить код, сделать запрос к API, прочитать файл).
|
||
2. **Resources (Ресурсы)** — данные, которые ИИ может читать (текстовые файлы, логи, таблицы, данные из БД).
|
||
3. **Prompts (Промпты)** — готовые шаблоны контекста или команд, которые пользователь может выбрать для модели. [1, 2, 3]
|
||
|
||
С технической точки зрения общение идет через JSON-RPC. Клиент отправляет запросы вроде `tools/list` (получить список инструментов) и `tools/call` (вызвать конкретный инструмент с аргументами). [1]
|
||
|
||
## Как сделать свой MCP сервер (на примере Python)
|
||
|
||
Проще всего использовать официальный SDK. Напишем простой сервер на Python, который предоставляет ИИ один инструмент: калькулятор стоимости доставки.
|
||
|
||
### Шаг 1. Установка библиотек
|
||
|
||
Вам понадобится официальный SDK от Anthropic и mcp. [3]
|
||
|
||
```bash
|
||
pip install mcp pydantic
|
||
```
|
||
|
||
### Шаг 2. Код сервера (server.py)
|
||
|
||
Создайте файл и опишите логику. Сервер будет работать через стандартный ввод/вывод (Stdio), что является стандартом для локальных MCP-серверов. [1]
|
||
|
||
```python
|
||
import asyncio
|
||
from mcp.server.models import InitializationOptions
|
||
from mcp.server import Notification, Server
|
||
import mcp.types as types
|
||
from mcp.server.stdio import stdio_server
|
||
|
||
# Инициализируем сервер
|
||
server = Server("my-delivery-calculator")
|
||
|
||
# 1. Регистрируем инструмент (Tool)
|
||
|
||
@server.list_tools()
|
||
async def handle_list_tools() -> list[types.Tool]:
|
||
return [
|
||
types.Tool(
|
||
name="calculate_delivery",
|
||
description="Рассчитывает стоимость доставки в зависимости от расстояния и веса.",
|
||
inputSchema={
|
||
"type": "object",
|
||
"properties": {
|
||
"distance_km": {"type": "number", "description": "Расстояние в километрах"},
|
||
"weight_kg": {"type": "number", "description": "Вес груза в кг"}
|
||
},
|
||
"required": ["distance_km", "weight_kg"]
|
||
}
|
||
)
|
||
]
|
||
|
||
# 2. Описываем логику выполнения этого инструмента
|
||
|
||
@server.call_tool()
|
||
async def handle_call_tool(
|
||
name: str, arguments: dict | None
|
||
) -> list[types.TextContent]:
|
||
if name == "calculate_delivery":
|
||
if not arguments:
|
||
raise ValueError("Отсутствуют аргументы")
|
||
|
||
distance = arguments.get("distance_km", 0)
|
||
weight = arguments.get("weight_kg", 0)
|
||
|
||
# Простая бизнес-логика
|
||
price = (distance * 10) + (weight * 50)
|
||
|
||
return [
|
||
types.TextContent(
|
||
type="text",
|
||
text=f"Стоимость доставки составляет {price} рублей."
|
||
)
|
||
]
|
||
raise ValueError(f"Инструмент {name} не найден")
|
||
|
||
# 3. Запуск сервера через Stdio
|
||
async def main():
|
||
async with stdio_server() as (read_stream, write_stream):
|
||
await server.run(
|
||
read_stream,
|
||
write_stream,
|
||
InitializationOptions(
|
||
server_name="my-delivery-calculator",
|
||
server_version="0.1.0",
|
||
capabilities=server.get_capabilities()
|
||
)
|
||
)
|
||
|
||
if __name__ == "__main__":
|
||
asyncio.run(main())
|
||
```
|
||
|
||
---
|
||
|
||
## Как протестировать и подключить?
|
||
|
||
1. **Через MCP Inspector**: Anthropic предоставляет инструмент для отладки. Запустите команду в терминале для визуального тестирования вашего сервера:
|
||
|
||
```bash
|
||
npx @modelcontextprotocol/inspector python server.py
|
||
```
|
||
|
||
Откроется веб-интерфейс, где можно проверить ответы API.
|
||
|
||
2. **В Claude Desktop**: Откройте конфигурационный файл (в Windows: `%APPDATA%\Claude\claude_desktop_config.json`, в macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`) и добавьте ваш сервер:
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"my-calculator": {
|
||
"command": "python",
|
||
"args": ["/абсолютный/путь/к/server.py"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
После перезапуска Claude увидит ваш инструмент и сможет вызывать его для расчетов. [3, 4]
|
||
|
||
---
|
||
|
||
Развертывание MCP-сервера на Vercel накладывает важное техническое ограничение: [Vercel](https://vercel.com/) работает на Serverless-функциях, поэтому стандартный локальный протокол связи (через терминал Stdio) здесь использовать нельзя.
|
||
|
||
Вместо этого удаленные серверы общаются через SSE (Server-Sent Events) и POST-запросы. Vercel предоставляет официальный пакет `@vercel/mcp-adapter`, который делает за вас всю грязную работу по управлению сессиями в Serverless-среде. [1, 2, 3]
|
||
|
||
Ниже пошаговый план, как создать такой сервер на SvelteKit и развернуть на Vercel. [3, 4]
|
||
|
||
---
|
||
|
||
## Шаг 1. Инициализация SvelteKit-проекта
|
||
|
||
Если у вас еще нет проекта, создайте его:
|
||
|
||
```bash
|
||
npm create svelte@latest my-mcp-server
|
||
cd my-mcp-server
|
||
npm install
|
||
```
|
||
|
||
Установите необходимые зависимости для работы MCP-сервера в среде Vercel: [4]
|
||
|
||
```bash
|
||
npm install @modelcontextprotocol/sdk @vercel/mcp-adapter
|
||
npm install -D @sveltejs/adapter-vercel
|
||
```
|
||
|
||
Убедитесь, что в файле `svelte.config.js` подключен верный адаптер: [5]
|
||
|
||
```js
|
||
import adapter from "@sveltejs/adapter-vercel";
|
||
import { vitePreprocess } from "@sveltejs/vite-plugin-svelte";
|
||
|
||
/** @type {import('@sveltejs/kit').Config} */
|
||
const config = {
|
||
preprocess: vitePreprocess(),
|
||
kit: {
|
||
adapter: adapter(), // Адаптер для Vercel
|
||
},
|
||
};
|
||
|
||
export default config;
|
||
```
|
||
|
||
---
|
||
|
||
## Шаг 2. Создание API эндпоинта (+server.ts)
|
||
|
||
По спецификации MCP на базе SSE, серверу требуются два роута: один открывает бесконечный поток для чтения событий (SSE), а второй принимает входящие POST-команды от клиента. Пакет `@vercel/mcp-adapter` объединяет их в один обработчик. [2, 6]
|
||
|
||
Создайте файл `src/routes/api/mcp/+server.ts` и добавьте следующий код:
|
||
|
||
```typescript
|
||
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
||
import { z } from "zod";
|
||
import { createActionHandler } from "@vercel/mcp-adapter";
|
||
import type { RequestHandler } from "./$types";
|
||
|
||
// 1. Инициализируем стандартный MCP-сервер из SDK Anthropic
|
||
const server = new McpServer({
|
||
name: "SvelteKit MCP Server",
|
||
version: "1.0.0",
|
||
});
|
||
|
||
// 2. Регистрируем ваш инструмент (Tool)
|
||
server.tool(
|
||
"getWeather",
|
||
"Возвращает текущую погоду для указанного города",
|
||
{
|
||
city: z.string().describe("Название города на английском или русском"),
|
||
},
|
||
async ({ city }) => {
|
||
// Здесь может быть ваш реальный fetch к какому-нибудь Weather API
|
||
return {
|
||
content: [
|
||
{
|
||
type: "text",
|
||
text: `В городе ${city} сейчас отличная погода, +22°C, солнечно.`,
|
||
},
|
||
],
|
||
};
|
||
},
|
||
);
|
||
|
||
// 3. Создаем обработчик для Vercel с помощью адаптера.
|
||
// Адаптер автоматически поддерживает Streamable HTTP и SSE.
|
||
const mcpHandler = createActionHandler(server);
|
||
|
||
// Экспортируем методы для SvelteKit
|
||
export const GET: RequestHandler = async ({ request }) => {
|
||
return mcpHandler(request);
|
||
};
|
||
|
||
export const POST: RequestHandler = async ({ request }) => {
|
||
return mcpHandler(request);
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## Шаг 3. Деплой на Vercel
|
||
|
||
1. Запуште ваш код в Git-репозиторий (GitHub, GitLab или Bitbucket).
|
||
2. Зайдите в панель управления Vercel и нажмите **Add New > Project**.
|
||
3. Выберите ваш репозиторий. Vercel автоматически определит, что это SvelteKit, и выставит правильные настройки сборки.
|
||
4. Нажмите **Deploy**. [7]
|
||
|
||
После завершения деплоя вы получите URL вашего сайта, например: `https://my-mcp-server.vercel.app`. Ваш MCP эндпоинт будет доступен по адресу `https://<ваш-проект>.vercel.app`.
|
||
|
||
## Шаг 4. Подключение к клиенту (Cursor / Claude Desktop)
|
||
|
||
Поскольку сервер теперь находится в сети и работает по протоколу SSE, его настройка в приложениях немного отличается от локальной. [2]
|
||
|
||
### Для Cursor (и аналогичных IDE):
|
||
|
||
1. Откройте **Settings > Features > MCP**.
|
||
2. Нажмите **+ Add New MCP Server**.
|
||
3. Заполните поля:
|
||
- **Name**: `SvelteKit-MCP`
|
||
- **Type**: из выпадающего списка выберите `SSE`.
|
||
- **URL**: `https://<ваш-проект>.vercel.app` [8]
|
||
|
||
### Для Claude Desktop:
|
||
|
||
Откройте файл конфигурации `claude_desktop_config.json` и пропишите вызов через команду `curl` или встроенный в Node.js транспорт (утилита автоматически преобразует SSE в понятный для Claude формат):
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"sveltekit-remote-mcp": {
|
||
"command": "npx",
|
||
"args": ["-y", "@modelcontextprotocol/inspector", "sse", "https://<ваш-проект>.vercel.app"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## Важные нюансы при работе на Vercel:
|
||
|
||
- **Таймауты serverless-функций**: На бесплатном тарифе Vercel (Hobby) лимит на выполнение функции составляет 10–15 секунд. Убедитесь, что ваши инструменты (запросы к сторонним API, вычисления) укладываются в это время, иначе соединение оборвется.
|
||
- **Базы данных и переменные окружения**: Если вашему инструменту понадобятся API-ключи, обязательно добавьте их в панель Vercel в разделе **Project Settings > Environment Variables**. [9, 10]
|
||
|
||
---
|
||
|
||
Поскольку данные статичны, мы можем сделать код максимально чистым, используя TypeScript и встроенную валидацию через Zod.
|
||
|
||
Вот готовый пример реализации файла `src/routes/api/mcp/+server.ts`, где данные (например, документация по вашему проекту или готовая база знаний) хранятся прямо внутри:
|
||
|
||
```typescript
|
||
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
||
import { z } from "zod";
|
||
import { createActionHandler } from "@vercel/mcp-adapter";
|
||
import type { RequestHandler } from "./$types";
|
||
|
||
// 1. Статические данные (база знаний сервера)
|
||
const KNOWLEDGE_BASE: Record<string, string> = {
|
||
api: "Наш API использует методы GET для чтения и POST для отправки команд.",
|
||
deploy: "Деплой автоматизирован через Vercel Git Integration при каждом пуше в main.",
|
||
contacts: "Техническая поддержка доступна по адресу support@mycompany.com.",
|
||
rules: "Все новые фичи должны быть покрыты тестами перед слиянием (ветка staging).",
|
||
};
|
||
|
||
// 2. Инициализируем MCP-сервер
|
||
const server = new McpServer({
|
||
name: "SvelteKit Static MCP",
|
||
version: "1.0.0",
|
||
});
|
||
|
||
// 3. Регистрируем инструмент для поиска по готовым данным
|
||
server.tool(
|
||
"getStaticData",
|
||
"Возвращает готовую справочную информацию по ключевому слову (api, deploy, contacts, rules).",
|
||
{
|
||
topic: z.enum(["api", "deploy", "contacts", "rules"]).describe("Ключевое слово темы для поиска"),
|
||
},
|
||
async ({ topic }) => {
|
||
// Извлекаем уже готовые данные
|
||
const info = KNOWLEDGE_BASE[topic];
|
||
|
||
return {
|
||
content: [
|
||
{
|
||
type: "text",
|
||
text: info || `Информация по теме "${topic}" не найдена.`,
|
||
},
|
||
],
|
||
};
|
||
},
|
||
);
|
||
|
||
// 4. Настройка адаптера для работы с Vercel Serverless
|
||
const mcpHandler = createActionHandler(server);
|
||
|
||
export const GET: RequestHandler = async ({ request }) => mcpHandler(request);
|
||
export const POST: RequestHandler = async ({ request }) => mcpHandler(request);
|
||
```
|
||
|
||
## Как это будет работать для ИИ:
|
||
|
||
Когда вы подключите этот сервер к Cursor или Claude Desktop, модель поймет, какие темы доступны (благодаря `z.enum`). Если вы спросите ИИ: «Как связаться с поддержкой?» или «Каковы правила деплоя?», модель автоматически вызовет инструмент `getStaticData` с нужным параметром и мгновенно получит зашитый в код ответ.
|
||
|
||
## Что делать дальше?
|
||
|
||
1. Замените ключи и тексты в объекте `KNOWLEDGE_BASE` на ваши реальные данные.
|
||
2. Обновите список доступных тем в `z.enum([...])`.
|
||
3. Сделайте `git commit` и `git push` — Vercel сам пересоберет проект за пару секунд.
|
||
|
||
---
|
||
|
||
## Вот 3 лучших способа проверить валидность вашего сервера от самого простого к продвинутому.
|
||
|
||
### Способ 1. Самый быстрый (в браузере за 5 секунд)
|
||
|
||
Так как ваш сервер развернут на Vercel и принимает GET-запросы, вы можете проверить его прямо в браузере или через curl.
|
||
|
||
1. Откройте браузер и перейдите по адресу вашего эндпоинта (например, `https://<ваш-проект>.vercel.app`).
|
||
2. Что вы должны увидеть: Браузер должен начать бесконечную загрузку страницы или отобразить текстовый поток (SSE Stream), начинающийся со строки:
|
||
|
||
```
|
||
event: endpoint
|
||
data: /api/mcp?session_id=...
|
||
```
|
||
|
||
Если вы увидели эту строку и статус ответа `200 OK` — транспортный уровень SSE работает корректно.
|
||
|
||
---
|
||
|
||
### Способ 2. Официальный веб-интерфейс (MCP Inspector)
|
||
|
||
Команда Anthropic создала специальную интерактивную панель для тестирования локальных и удаленных серверов.
|
||
|
||
Запустите в терминале команду (утилита скачается и запустится автоматически через npx):
|
||
|
||
```bash
|
||
npx @modelcontextprotocol/inspector sse https://<ваш-проект>.vercel.app
|
||
```
|
||
|
||
(Замените URL на ваш адрес на Vercel)
|
||
|
||
Что произойдет дальше:
|
||
|
||
1. В терминале появится ссылка (обычно `http://localhost:5173`). Откройте ее в браузере.
|
||
2. Вы увидите графическую панель управления вашим MCP-сервером.
|
||
3. Нажмите кнопку **List Tools** — в интерфейсе должен появиться ваш инструмент `getStaticData` со всей схемой параметров.
|
||
4. Вы можете заполнить поля формы (например, выбрать тему `api`) и нажать **Call Tool**. Вы мгновенно увидите сырой JSON-ответ от Vercel.
|
||
|
||
> Это эталонный метод проверки: если Inspector работает без ошибок, значит, любой ИИ (Cursor, Claude) гарантированно поймет ваш сервер.
|
||
|
||
### Способ 3. Проверка через Postman / Insomnia / cURL
|
||
|
||
Если вы хотите убедиться, что JSON-RPC команды обрабатываются правильно, можно сымитировать запрос от ИИ вручную. Для этого нужно сделать POST-запрос, но с одной важной деталью: протокол SSE требует ID сессии, который сервер выдает при GET-запросе.
|
||
|
||
Проще всего сделать это через curl в два шага:
|
||
|
||
**Шаг 1: Инициализация сессии (GET)**
|
||
|
||
```bash
|
||
curl -i https://<ваш-проект>.vercel.app
|
||
```
|
||
|
||
В ответе найдите строку `data: /api/mcp?session_id=ХХХХХХ`. Скопируйте этот хвост с ID сессии.
|
||
|
||
**Шаг 2: Вызов инструмента (POST)**
|
||
|
||
Отправьте JSON-RPC запрос на полученный адрес сессии:
|
||
|
||
```bash
|
||
curl -X POST "https://<ваш-проект>.vercel.app/api/mcp?session_id=ХХХХХХ" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"jsonrpc": "2.0",
|
||
"id": 1,
|
||
"method": "tools/call",
|
||
"params": {
|
||
"name": "getStaticData",
|
||
"arguments": {
|
||
"topic": "api"
|
||
}
|
||
}
|
||
}'
|
||
```
|
||
|
||
Правильный ответ сервера должен выглядеть так:
|
||
|
||
```json
|
||
{
|
||
"jsonrpc": "2.0",
|
||
"id": 1,
|
||
"result": {
|
||
"content": [
|
||
{
|
||
"type": "text",
|
||
"text": "Наш API использует методы GET для чтения и POST для отправки команд."
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|