Протокол контекста модели (MCP): как начать
tech-stories mcp ai-agent-mcp mcp-server mcp-architecture what-is-mcp mcp-guide mcp-tutorial model-context-protocol

Протокол контекста модели (MCP): как начать

25 июля 2025 г.

Мы все были там - ваша любимая модель ИИ - это либо галлюцинирует, либо дает ответы, не относящиеся к вашей конкретной проблеме из -за отсутствия контекста и/или инструментов.Разговор о разочарованииПолем

Именно это проблема, которую антропная команда решила решить со стандартом модельного протокола контекста (MCP).

В этом коротком руководстве вы узнаете все о MCP, как начать их использовать и даже построить один из своих.

Давай вдамся!

Что такое MCP?

MCP - этооткрытый стандартЭто подключает модели ИИ с внешними инструментами и источниками данных. Вместо того, чтобы помощники искусственного интеллекта ограничивались своими данными обучения, MCP позволяет им взаимодействовать с базами данных, файловыми системами, API и пользовательскими приложениями в режиме реального времени.

Думать об этом какUSB-C для AIПриложения - стандартизированный способ подключения моделей AI к различным источникам данных, инструментам и услугам.

Преимущества использования MCP

Подключиться к реальным инструментам и данным: MCP ломает стены между моделями ИИ и вашей реальной рабочей средой. Ваш помощник по искусственному ИИ может читать файлы, базы данных запросов, вызовать API и выполнять сценарии - все с вашего разрешения.

Постройте один раз, используйте повсюду: Ключевой силой MCP является совместимость. Постройте MCP-сервер один раз, и он работает с любым MCP-совместимым клиентом ИИ. Независимо от того, используете ли вы настольный компьютер, курсор, код против кода или десятки других приложений, все они могут использовать одни и те же серверы MCP.

Включить многосистемную связь: MCP -серверы могут действовать как мосты между различными системами и моделями ИИ. Вы можете создавать рабочие процессы, где агенты искусственного интеллекта общаются друг с другом через общие серверы MCP, обеспечивая сложную многоэтапную автоматизацию.

Продлить без восстановления: Вместо всех приложений для AI, создающей свои собственные интеграции, MCP предоставляет стандартный интерфейс. Разработчики могут расширять возможности ИИ, не восстанавливая одни и те же соединения снова и снова.

Поддерживать контроль и безопасность: Вы контролируете, к каким данным и инструментам, который ваш ИИ может получить доступ. Серверы MCP работают с разрешениями, которые вы им предоставляете, и многие клиенты просят одобрение, прежде чем выполнять потенциально конфиденциальные операции.

Доступ к информации в реальном времени: В отличие от статических данных обучения, MCP позволяет моделям искусственного интеллекта извлекать текущую информацию из живых систем-погода, недавние электронные письма, последние записи базы данных или статус системы в реальном времени.

Чему вы узнаете

Это руководство перенесет вас из знаний о нулевом MCP для создания собственного функционального MCP -сервера. Вы начнете с использования предварительно построенных серверов с настольным компьютером Claude, чтобы понять основы. Затем мы переключимся на курсор для работы по разработке и построим погодный сервер, который получает прогнозы и оповещения в режиме реального времени.

В конце концов вы поймете основные концепции MCP, узнаете, как отладить общие проблемы, и вы будете основываться на создании серверов для ваших конкретных потребностей.

Основы MCP: Использование предварительно построенных серверов с настольным компьютером Claude

Давайте начнем с самого простого введения в MCP. Мы будем использовать Claude Desktop, потому что он имеет отличную поддержку MCP и требует нулевой кодирования, чтобы начать.

Настройка рабочего стола Claude с MCP

Сначала скачатьКлод настольный компьютерЕсли вы еще этого не сделали. Выберите MacOS или Windows (Linux еще не поддерживается). Убедитесь, что вы запускаете последнюю версию, нажав на меню Claude и выбрав «Проверка для обновлений ...»

Теперь мы добавим сервер MCP файловой системы, который позволяет Клоду читать и записывать файлы на вашем компьютере. Не волнуйтесь - он попросит разрешения, прежде чем что -либо делать.

Настройка сервера MCP

Откройте меню Claude на вашем компьютере и выберите «Настройки ...» (не настройки учетной записи Claude в окне приложения).

Нажмите «Разработчик» на левой боковой панели, затем нажмите «Редактировать конфигурацию». Это создаст и откроет файл конфигурации:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Окна: %APPDATA%\Claude\claude_desktop_config.json

Если файл не открывается автоматически или вы не можете его найти, разверните и выполните эти шаги:

Вариант 1: используйте текстовый редактор по умолчанию

# On Mac
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# On Windows  
notepad %APPDATA%\Claude\claude_desktop_config.json

Вариант 2: Навигация с Finder/File Explorer

  • Маки: Нажмите CMD+SHIFT+G в Finder, тип~/Library/Application Support/Claude/
  • Окна: Нажмите Win+R, тип%APPDATA%\Claude\, нажмите Enter </details>

Замените содержимое файла этой конфигурацией JSON:

На Mac/linux:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourusername/Desktop",
        "/Users/yourusername/Downloads"
      ]
    }
  }
}

В окнах:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\yourusername\\Desktop",
        "C:\\Users\\yourusername\\Downloads"
      ]
    }
  }
}

Заменятьyourusernameс вашим настоящим именем пользователя (бегиwhoamiВ CLI, если вы не уверены). Пути должны указывать на каталоги, которые вы хотите, чтобы Клод получил доступ и изменил.

Установите node.js (требуется)

Этот сервер MCP использует node.js. Убедитесь, что вы установили, открывая терминал (Mac) или командную строку (Windows) и запустив:

node --version

Если вы получите «Команда, не найденная» или «Узел не распознается», загрузите node.js изnodejs.orgПолем

Сохранятьфайл конфигурации иперезапускClaude Desktop полностью.

Тестирование вашего первого соединения MCP

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

Search and Tools Menu

Источник изображения:Сайт MCP

Если вы получите ошибку, такую как «Не удалось прикрепить файловую систему сервера MCP» или «MCP File -System: сервер отключен», следуйте этим шагам для отладки:

  • Запустите эту команду, чтобы просмотреть журналы настольных компьютеров Claude:
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

Совет: вставьте свои журналы в LLM, чтобы получить помощь отладки

Теперь попробуйте эти команды с Клодом:

  • "Можете ли вы написать короткое стихотворение и сохранить его на мой рабочий стол?"
  • "Какие файлы в моей папке загрузки?"
  • «Можете ли вы создать новую папку под названием« mcp-test »на моем рабочем столе?»

Когда Клод предлагает использовать инструменты, вы увидите подсказку разрешения. Нажмите «Разрешить», чтобы позволить ему продолжаться. Теперь он должен иметь возможность получить доступ к вашим файлам.

Поздравляю! Вы только что испытали MCP в действии. Теперь Claude может взаимодействовать с вашей файловой системой, потому что вы подключили ее к серверу MCP, который предоставляет файловые операции.

Что только что случилось?

Вот простой поломка:

  1. MCP -сервер: Установленный вами сервер файловой системы предоставляет инструменты для операций файлов
  2. MCP клиент: Claude Desktop подключается к вашему серверу и получает список доступных инструментов
  3. ИИ интеграция: Когда вы просите Claude работать с файлами, он автоматически использует соответствующие инструменты
  4. Пользовательский контроль: Вы одобряете каждое действие, прежде чем оно произойдет

Эта настройка клиентского сервера означает, что вы можете подключить Claude к базам данных, API, другим приложениям или пользовательским инструментам, которые вы создаете сами.

Диаграмма ниже дает визуальное представление о том, что происходит.

MCP-architecture

Источник изображения:Сайт MCP

Как использовать MCP с курсором для развития с AI на основе AI

Claude Desktop отлично подходит для общего использования, но для лучшего использования MCP в ваших рабочих процессах кодирования вы хотите использовать их с таком клиентом, какКурсор(любимый редактор кода с AI на двигателе ИИ).

Вы также можете использовать VSCODE, если вы бумер.

Настройка MCP в курсоре

Курсор имеет встроенную поддержку MCP. Чтобы включить это:

  1. Скачатьи установить курсор
  2. Откройте настройки курсора
  3. Нажмите на «Инструменты и интеграции»
  4. Нажмите кнопку «Добавить новый MCP»,mcp.jsonФайл должен открыть
  5. Вставьте фрагмент конфигурации JSON из более раннего (дляфайловая системасервер) вmcp.jsonфайл

Это позволяет вам подключаться к тому же серверу файловой системы, который вы использовали с Claude Desktop, но на этот раз он интегрирован в вашу среду кодирования.

Сила здесь в том, что ИИ Курсора теперь может:

  • Прочитайте файлы проекта, чтобы понять контекст
  • Создать новые файлы и папки
  • Редактировать существующий код
  • Запустить сценарии и команды
  • Все же, сохраняя полную осведомленность о структуре проекта

Попробуйте открыть проект в курсоре и попросить его обратить внимание на файл снаружи на вашем компьютере для контекста. Вы увидите, как MCP превращает ИИ из генерального помощника в партнера по кодированию.

Время для построения: создание собственного MCP -сервера с курсором

Теперь, для веселой части - создание собственного сервера MCP. Мы создадим погодный сервер, который может принести прогнозы и оповещения. Этот пример работает хорошо, потому что он практичен, просто для понимания и показывает все основные концепции MCP.

Настройка проекта

Откройте курсор и создайте новую папку для вашего проекта:

mkdir weather-mcp-server
cd weather-mcp-server

Мы будем использовать Python для этого примера. Создайте новый файл с названиемweather.pyи вставьте в этот код:

from typing import Any
import httpx
from mcp.server.fastmcp import FastMCP

# Initialize FastMCP server
mcp = FastMCP("weather")

# Constants for the National Weather Service API
NWS_API_BASE = "https://api.weather.gov"
USER_AGENT = "weather-mcp-server/1.0"

Вот что делает каждый импорт:

  • typing.Any: Помогает с подсказками типа (делает код чистым)
  • httpx: Современная клиентская библиотека HTTP для выполнения веб -запросов (например,requestsно асинхронозвенно)
  • mcp.server.fastmcp: Структура MCP, которая обрабатывает все детали протокола для нас

АFastMCPКласс автоматически преобразует ваши функции Python в инструменты MCP, используя подписи функций и Docstrings.

Мы используем API NWS (Национальная служба погоды) (https://api.weather.gov) иUSER_AGENTОпределяет наш сервер в API (хорошее гражданство API).

Далее установите требуемые зависимости:

pip install mcp httpx

Добавление вспомогательных функций

Добавьте эти вспомогательные функции для обработки запросов API - они делают тяжелую работу по разговору с погодным API:

async def make_nws_request(url: str) -> dict[str, Any] | None:
    """Make a request to the NWS API with proper error handling."""
    headers = {
        "User-Agent": USER_AGENT,
        "Accept": "application/geo+json"
    }
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(url, headers=headers, timeout=30.0)
            response.raise_for_status()
            return response.json()
        except Exception:
            return None

def format_alert(feature: dict) -> str:
    """Format an alert feature into a readable string."""
    props = feature["properties"]
    return f"""
Event: {props.get('event', 'Unknown')}
Area: {props.get('areaDesc', 'Unknown')}
Severity: {props.get('severity', 'Unknown')}
Description: {props.get('description', 'No description available')}
Instructions: {props.get('instruction', 'No specific instructions provided')}
"""

Аmake_nws_requestФункция - наш общий абонент API, который:

  • Устанавливает надлежащие заголовки (пользовательский агент идентифицирует нас, Accement рассказывает API, который мы хотим формат Geojson)
  • Использованиеasync withЧтобы правильно управлять подключением HTTP
  • Включает в себя обработку ошибок - если что -то пойдет не так, она возвращаетсяNoneВместо того, чтобы сбой
  • Имеет 30-секундный тайм-аут для предотвращения висящих запросов

Аformat_alertФункция принимает необработанный ответ API и делает его читаемым человеком. API NWS возвращает комплексные объекты JSON, но нам нужна только ключевая информация, отформатированная хорошо.

Создание вашего первого инструмента

Теперь давайте добавим инструмент, который приносит предупреждения о погоде для данного состояния:

@mcp.tool()
async def get_alerts(state: str) -> str:
    """Get weather alerts for a US state.

    Args:
        state: Two-letter US state code (e.g. CA, NY)
    """
    url = f"{NWS_API_BASE}/alerts/active/area/{state}"
    data = await make_nws_request(url)

    if not data or "features" not in data:
        return "Unable to fetch alerts or no alerts found."

    if not data["features"]:
        return "No active alerts for this state."

    alerts = [format_alert(feature) for feature in data["features"]]
    return "\n---\n".join(alerts)

Это наш первый инструмент MCP! Вот как это работает:

А@mcp.tool()Декоратор рассказывает FastMCP: «Эта функция должна быть доступна в качестве инструмента для клиентов искусственного интеллекта». Фреймворк автоматически:

  • Читает подпись функции, чтобы понять, какие параметры ей нужны
  • Использует Docstring в качестве описания инструмента
  • Преобразует типовые подсказки в правильную схему для моделей искусственного интеллекта

Сама функцияСоздает URL для конечной точки оповещения NWS, делает запрос и обрабатывает ответ. Обратите внимание, как мы справляемся с разными сценариями:

  • Отказ API → вернуть сообщение об ошибке
  • Не найдено оповещений → вернуть дружелюбное сообщение «Нет оповещений»
  • Оповещения найдены → форматировать каждый и присоединиться к ним с разделителями

Почему это работает хорошо: Модели ИИ получают четкое описание («Получите оповещения о погоде для состояния США») и точно знайте, какой параметр предоставить (код состояния с двумя буквами). Возвращаемое значение всегда является читаемой человеком строкой.

Добавление второго инструмента

Давайте добавим еще один инструмент для прогнозов погоды. Это немного сложнее, потому что это требует двух вызовов API:

@mcp.tool()
async def get_forecast(latitude: float, longitude: float) -> str:
    """Get weather forecast for a location.

    Args:
        latitude: Latitude of the location
        longitude: Longitude of the location
    """
    # First get the forecast grid endpoint
    points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"
    points_data = await make_nws_request(points_url)

    if not points_data:
        return "Unable to fetch forecast data for this location."

    # Get the forecast URL from the points response
    forecast_url = points_data["properties"]["forecast"]
    forecast_data = await make_nws_request(forecast_url)

    if not forecast_data:
        return "Unable to fetch detailed forecast."

    # Format the periods into a readable forecast
    periods = forecast_data["properties"]["periods"]
    forecasts = []
    for period in periods[:5]:  # Only show next 5 periods
        forecast = f"""
{period['name']}:
Temperature: {period['temperature']}°{period['temperatureUnit']}
Wind: {period['windSpeed']} {period['windDirection']}
Forecast: {period['detailedForecast']}
"""
        forecasts.append(forecast)

    return "\n---\n".join(forecasts)

Вот как работает этот инструмент:

Шаг 1: Получите точку сетки- NWS API не принимает координаты напрямую для прогнозов. Сначала вам нужно преобразовать координаты LAT/LNG в их внутреннюю систему сети, вызывая/points/конечная точка.

Шаг 2: Получите фактический прогноз- Первый вызов API возвращает URL для конечной точки прогноза, специфичной для этого места. Затем мы называем этот URL, чтобы получить фактические данные прогноза.

Обработка данных- Прогноз возвращается как множество «периодов» (сегодня вечером, завтра, завтра вечером и т. Д.). Мы:

  • Возьмите только первые 5 периодов (чтобы избежать подавляющего вывода)
  • Извлеките ключевую информацию из каждого периода
  • Форматируйте это прочитаемым способом

Запуск сервера

Добавьте это в конце вашего файла:

if __name__ == "__main__":
    mcp.run(transport='stdio')

Теперь вы можете проверить свой сервер прямо в терминале курсора:

python weather.py

Если у вас нет ошибок, ваш MCP -сервер живет!

from typing import Any
import httpx
from mcp.server.fastmcp import FastMCP

# Initialize FastMCP server
mcp = FastMCP("weather")

# Constants for the National Weather Service API
NWS_API_BASE = "https://api.weather.gov"
USER_AGENT = "weather-mcp-server/1.0"

async def make_nws_request(url: str) -> dict[str, Any] | None:
    """Make a request to the NWS API with proper error handling."""
    headers = {
        "User-Agent": USER_AGENT,
        "Accept": "application/geo+json"
    }
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(url, headers=headers, timeout=30.0)
            response.raise_for_status()
            return response.json()
        except Exception:
            return None

def format_alert(feature: dict) -> str:
    """Format an alert feature into a readable string."""
    props = feature["properties"]
    return f"""
    Event: {props.get('event', 'Unknown')}
    Area: {props.get('areaDesc', 'Unknown')}
    Severity: {props.get('severity', 'Unknown')}
    Description: {props.get('description', 'No description available')}
    Instructions: {props.get('instruction', 'No specific instructions provided')}
"""

@mcp.tool()
async def get_alerts(state: str) -> str:
    """Get weather alerts for a US state.

    Args:
        state: Two-letter US state code (e.g. CA, NY)
    """
    url = f"{NWS_API_BASE}/alerts/active/area/{state}"
    data = await make_nws_request(url)

    if not data or "features" not in data:
        return "Unable to fetch alerts or no alerts found."

    if not data["features"]:
        return "No active alerts for this state."

    alerts = [format_alert(feature) for feature in data["features"]]
    return "\n---\n".join(alerts)

@mcp.tool()
async def get_forecast(latitude: float, longitude: float) -> str:
    """Get weather forecast for a location.

    Args:
        latitude: Latitude of the location
        longitude: Longitude of the location
    """
    # First get the forecast grid endpoint
    points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"
    points_data = await make_nws_request(points_url)

    if not points_data:
        return "Unable to fetch forecast data for this location."

    # Get the forecast URL from the points response
    forecast_url = points_data["properties"]["forecast"]
    forecast_data = await make_nws_request(forecast_url)

    if not forecast_data:
        return "Unable to fetch detailed forecast."

    # Format the periods into a readable forecast
    periods = forecast_data["properties"]["periods"]
    forecasts = []
    for period in periods[:5]:  # Only show next 5 periods
        forecast = f"""
    {period['name']}:
    Temperature: {period['temperature']}°{period['temperatureUnit']}
    Wind: {period['windSpeed']} {period['windDirection']}
    Forecast: {period['detailedForecast']}
"""
        forecasts.append(forecast)

    return "\n---\n".join(forecasts)

if __name__ == "__main__":
    mcp.run(transport='stdio')

Подключение к курсору

Чтобы использовать ваш погодный сервер с помощью Cursor's AI, вам необходимо настроить курсор для подключения к нему. Добавить это вmcp.jsonФайл из более раннего в настройках курсора (новая запись подmcpServers):

{
  "weather": {
    "command": "python",
    "args": ["/absolute/path/to/your/weather.py"]
  }
}

Теперь, когда вы общаетесь с ИИ Cursor, вы можете задать такие вопросы, как:

  • "Каковы текущие оповещения о погоде в Калифорнии?"
  • «Получите мне прогноз для Сан -Франциско (Latitude 37.7749, долгота -122,4194)»

Обыкновенные GotChas и исправления

Проблемы пути: Всегда используйте абсолютные пути в вашей конфигурации. Относительные пути часто нарушаются, потому что рабочий каталог может не быть тем, что вы ожидаете.

Ошибки API: API Национальной службы погоды работает только для американских мест. Если вы тестируете с международными координатами, вы получите ошибки.

Проблемы с разрешением: Убедитесь, что ваш сценарий Python выполняется, и все зависимости установлены.

Инструмент не показывает: Если курсор не видит ваши инструменты, перезапустите курсор после обновления конфигурации.

Понимание основных понятий

Теперь, когда вы создали работающий MCP -сервер, давайте поймем три основных примитива MCP:

Инструменты: пусть модели искусственного интеллекта предпринимают действия

Инструменты - это функции, которые модели ИИ могут вызвать для выполнения действий. На нашем погодном сервере,get_alertsиget_forecastинструменты. Инструменты контролируются моделью - ИИ решает, когда их использовать на основе запросов пользователей.

Используйте инструменты, когда вы хотите, чтобы ИИ до:

  • Получить данные из API
  • Execute commands
  • Выполнить расчеты
  • Interact with external services

Ресурсы: дайте моделям AI доступ к данным

Ресурсы - это файлы или данные, которые модели ИИ могут прочитать для контекста. В отличие от инструментов, ресурсы контролируются приложениями - пользователь явно выбирает, какие ресурсы должны включать.

Use resources when you want to provide:

  • File contents
  • Записи базы данных
  • Ответы API
  • Документация

Подсказки: многоразовые шаблоны для общих задач

Подсказки - это предопределенные шаблоны, которые помогают пользователям выполнять конкретные задачи. Они контролируются пользователем и появляются в виде быстрых действий или команд SLASH в клиентских приложениях.

Используйте подсказки для:

  • Общие рабочие процессы
  • Стандартизированные форматы
  • Многоэтапные процессы
  • Шаблоны команды

Наш MCP использовал все три из них.

Отладка и устранение неполадок

Все пойдет не так, когда вы создаете серверы MCP. Вот как эффективно отлаживать их в курсоре.

Общие ошибки:

  • Ваш сервер не отображается в списке MCP курсора
  • Инструменты не выполняются, когда ИИ пытается их использовать
  • Сообщения об ошибках в терминале при запуске вашего сервера
  • Курсор не может подключиться к вашему серверу

Основные инструменты отладки

MCP инспекторВаш лучший друг для отладки. Установите его во всем мире:

npx @modelcontextprotocol/inspector path/to/your/weather.py

Инспектор позволяет вам:

  • Проверьте свой сервер без клиента искусственного интеллекта
  • Посмотрите, какие инструменты и ресурсы предоставляют ваш сервер
  • Выполнить инструменты вручную с помощью пользовательских входов
  • Просмотреть подробные сообщения об ошибках

Быстрые исправления, которые обычно работают

  1. Перезагрузить курсорПосле изменения конфигурации MCP
  2. Используйте абсолютные путивезде в вашей конфигурации
  3. Проверьте терминалДля сообщений об ошибках, когда ваш сервер запускается
  4. Проверьте с инспекторомПеред подключением к курсору
  5. Проверьте свою среду Pythonимеет все необходимые пакеты

Подробнееотладка MCPSПолем

Что дальше?

Теперь вы испытали MCP в качестве пользователя и создали свой собственный сервер. Вот как продолжать развивать свои навыки MCP.

Просмотрите существующие серверы MCP для вдохновения

  1. ПроверьтеОфициальный репозиторий серверов MCPЧтобы увидеть, что построили другие:

  • Разъемы базы данных(Postgresql, SQLite)

  • API интеграции(Github, Slack, Google Drive)

  • Инструменты разработки(GIT Operations, Анализ кода)

  • Инструменты производительности(Календарь, электронная почта, управление файлами)

    Каждый сервер показывает разные шаблоны и подходы, которые вы можете узнать, и черпать вдохновение для ваших собственных MCPS!

  1. Узнайте, какИспользуйте LLMSЧтобы построить MCP

Поздравляю! Вы не знали ничего о MCP к созданию рабочего сервера, который может работать с различными клиентами, чтобы сделать ИИ более полезным.

Это руководство предоставило вам основополагающие знания, чтобы начать создавать серверы для ваших конкретных потребностей. Инструменты искусственного интеллекта, которые вы используете каждый день, станут гораздо более мощными!

В следующей статье мы рассмотрим, как использовать MCP в курсоре, чтобы в 10 раз ваш производитель в качестве разработчика!

Оригинал

Recent Post

Categories

PREVIOUS ARTICLE
NEXT ARTICLE