2025-06-10 · Обновлено 2026-06-07

[!NOTE] Автоматический перевод Эта статья была автоматически переведена с оригинальной английской версии.

MCP Учебник по серверам с использованием uv и FastMCP: создание сервера FeatureStoreLite

В этом учебном пособии по серверам MCP показано, как с помощью FastMCP создать небольшой сервер хранилища функций, запустить его с использованием инструмента uv, и подключить к приложению Claude Desktop.

Кратко: Для предоставления агенту удобного локального инструмента достаточно небольшого сервера FastMCP. Используйте uv для настройки с возможностью повторения, ограничивайте объём обрабатываемых данных, проверяйте входные данные с помощью типизированных схем и тестируйте инструмент MCP перед подключением его к модель.

Что такое сервер MCP?

Модель Протокол контекста (MCP) представляет собой открытый стандарт, позволяющий подключать ассистенты AI к внешним источникам данных и инструментам. Он заменяет необходимость разработки отдельных кастомных решений для каждого инструмента на использование единого набора правил взаимодействия.

В этом уроке мы создадим сервер FeatureStoreLite MCP. Он располагается между LLM и хранилищем признаков (базой данных с заранее вычисленными ML признаками) и предоставляет инструменты для запроса и записи векторов признаков, идентифицированных по пользователю, продукту или документу.

Зачем разрабатывать это?

Вы — инженер ML, отладкающий пайплайн. Вместо того чтобы обращаться к СУБД или писать краткий скрипт для проверки значений признаков, вы напрямую задаёте вопрос Claude: «Каков вектор признаков пользователя user_123?» или «Покажите метаданные продукта product_abc.» Именно сервер MCP позволяет реализовать такой подход.

Зачем использовать uv?

Мы будем использовать UV для установки пакетов, разрешения зависимостей и управления виртуальной средой. Позже, uv run --with mcp[cli] ... Это также позволит конфигурации Claude Desktop напрямую указывать на свою зависимость. Благодаря этому исчезает необходимость в отдельной среде, которая может потерять синхронизацию.

Обзор архитектуры

Четыре компонента и способ их взаимодействия:

1. Пользователь задаёт вопрос на естественном языке.
2. Claude Desktop является клиентом MCP. Он выбирает соответствующий инструмент в зависимости от вопроса и запускает его.
3. Наше FastMCP сервер предоставляет доступ к get_feature и store_feature в качестве инструментов MCP.
4. SQLite служит основным хранилищем для векторов признаков.

2. Настройка и установка

2.1. Установка uv

Если у вас ещё нет uvустановите его. В остальной части руководства предполагается, что он уже у вас есть. PATH.

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or via Homebrew
brew install uv

2.2. Инициализация проекта

Создайте новую директорию и инициализируйте проект на Python. uv init создаёт pyproject.toml для вас.

# Create project directory
mkdir mcp-featurestore
cd mcp-featurestore

# Initialize Python project
uv init

# Add the MCP SDK with CLI tools
uv add "mcp[cli]"

3. Сборка сервера

Два файла, разделённые по функциональным областям:

1. database.py обрабатывает операции с SQLite. featurestore_server.py определяет сервер MCP.

3.1. Слой базы данных (database.py)

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

создать database.py:

# database.py
import json
import os
import sqlite3


def get_db_path() -> str:
    """Get the database path - always in the script's directory"""
    script_dir = os.path.dirname(os.path.abspath(__file__))
    return os.path.join(script_dir, "features.db")


def init_db() -> None:
    """Initialize the feature store database with table and sample data"""
    conn = sqlite3.connect(get_db_path())
    conn.execute("""
        CREATE TABLE IF NOT EXISTS features (
            key TEXT PRIMARY KEY,
            vector TEXT NOT NULL,
            metadata TEXT,
            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
        )
    """)

    # Sample data for experimentation
    example_features = [
        (
            "user_123",
            "[0.1, 0.2, -0.5, 0.8, 0.3, -0.1, 0.9, -0.4]",
            json.dumps({"type": "user", "id": 123, "segment": "premium"}),
        ),
        (
            "product_abc",
            "[0.7, -0.3, 0.4, 0.1, -0.8, 0.6, 0.2, -0.5]",
            json.dumps({"type": "product", "id": "abc", "category": "electronics"}),
        ),
    ]

    # Insert if not exists
    for key, vector, metadata in example_features:
        try:
            conn.execute(
                "INSERT INTO features (key, vector, metadata) VALUES (?, ?, ?)",
                (key, vector, metadata),
            )
        except sqlite3.IntegrityError:
            pass  # Already exists

    conn.commit()
    conn.close()


def get_db_connection() -> sqlite3.Connection:
    """Get a database connection"""
    return sqlite3.connect(get_db_path())


if __name__ == "__main__":
    init_db()
    print("✅ Database initialized successfully!")

Инициализируем базу данных:

uv run python database.py

3.2. Сервер MCP (featurestore_server.py)

FastMCP Выполняет основную часть работы. Достаточно добавить специальные атрибуты к обычной функции на Python, и она автоматически регистрируется в качестве инструмента или ресурса MCP. Документация функции становится описанием, которое видит LLM, поэтому её следует писать с учётом потребностей LLM, а не только для людей.

создать featurestore_server.py:

# featurestore_server.py
import json
from mcp.server.fastmcp import FastMCP
from database import get_db_connection, init_db

# Initialize the MCP Server
mcp = FastMCP("FeatureStoreLite")

# Ensure DB is ready when server starts
init_db()


@mcp.resource("schema://main")
def get_schema() -> str:
    """
    Resource: Provide the database schema.
    Resources are passive data that LLMs can read like files.
    """
    conn = get_db_connection()
    try:
        schema = conn.execute(
            "SELECT sql FROM sqlite_master WHERE type='table'"
        ).fetchall()
        return "\n".join(sql[0] for sql in schema if sql[0]) or "No tables found."
    finally:
        conn.close()


@mcp.tool()
def store_feature(key: str, vector: str, metadata: str | None = None) -> str:
    """
    Tool: Store a feature vector.
    Tools are executable functions that LLMs can call to perform actions.
    """
    conn = get_db_connection()
    try:
        # Validate that vector is valid JSON
        json.loads(vector)

        conn.execute(
            "INSERT OR REPLACE INTO features (key, vector, metadata) VALUES (?, ?, ?)",
            (key, vector, metadata),
        )
        conn.commit()
        return f"Successfully stored feature '{key}'"
    except json.JSONDecodeError:
        return "Error: Vector must be a valid JSON array string (e.g., '[0.1, 0.2]')"
    except Exception as e:
        return f"Error: {str(e)}"
    finally:
        conn.close()


@mcp.tool()
def get_feature(key: str) -> str:
    """
    Tool: Retrieve a feature vector by key.
    """
    conn = get_db_connection()
    try:
        row = conn.execute(
            "SELECT vector, metadata FROM features WHERE key = ?", (key,)
        ).fetchone()

        if row:
            return json.dumps(
                {
                    "key": key,
                    "vector": json.loads(row[0]),
                    "metadata": json.loads(row[1]) if row[1] else None,
                },
                indent=2,
            )
        return f"Feature '{key}' not found."
    finally:
        conn.close()


@mcp.tool()
def list_features() -> str:
    """
    Tool: List all available feature keys.
    """
    conn = get_db_connection()
    try:
        rows = conn.execute("SELECT key FROM features").fetchall()
        return json.dumps([row[0] for row in rows])
    finally:
        conn.close()


if __name__ == "__main__":
    mcp.run()

4. Тестирование с использованием инспектора MCP

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

uv run mcp dev featurestore_server.py

Эта команда запускает сервер и открывает инструмент Inspector в вашем браузере (обычно по адресу http://localhost:5173).

{width=“600”}

Вызов get_feature с key="user_123". Если для строки с семенем возвращается JSON, значит сервер функционирует корректно.

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

Как только инспектор подтвердит, что сервер работает корректно, зарегистрируйте его в Claude Desktop.

5.1. Настройка Claude

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

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

добавьте свой сервер в mcpServers объект:

{
    "mcpServers": {
        "featurestore": {
            "command": "uv",
            "args": [
                "run",
                "--with",
                "mcp[cli]",
                "mcp",
                "run",
                "/ABSOLUTE/PATH/TO/mcp-featurestore/featurestore_server.py"
            ]
        }
    }
}

Важно: путь к featurestore_server.py Здесь обязательно должен использоваться абсолютный путь. Релятивный путь приведёт к тихой ошибке, поскольку Claude Desktop запускается из другого рабочего каталога.

5.2. Как происходит взаимодействие

Вот что происходит в полном цикле при поиске функции в Claude:

1. Claude определяет доступные инструменты (get_feature, list_features, и так далее).
2. Система определяет, что для решения задачи требуются данные из хранилища признаков.
3. Она формирует tool call и отправляет его на ваш сервер.
4. Сервер запускает функцию на Python и возвращает результат.
5. Claude использует этот результат для формирования окончательного ответа.

5.3. Примеры запросов

Перезагрузите Claude Desktop и попробуйте несколько промпты:

1. «Перечислите все доступные функции». {width=“600”}

2. «Получить вектор признаков для user_123». {width=“600”}

3. «Сохранить новую характеристику для ‘new_item’ с вектором [0.5, 0.5] и метаданными {‘type’: ‘test’}».

6. Устранение неполадок

Несколько модусов сбоя, о которых стоит знать:

• «Не удалось установить соединение с сервером»:

  • Проверьте логи в ~/Library/Logs/Claude/mcp.log на macOS.
  • Убедитесь, что конфигурация использует абсолютный путь, а не относительный.
  • Убедитесь uv входит в состав Claude Desktop PATH. Если это не так, укажите полный двоичный путь (which uv это укажет, где он расположен).

• «Ошибка выполнения инструмента»:

  • Воспроизвести её в Инспекторе с uv run mcp dev featurestore_server.pyИнспектор отображает первоначальную ошибку, которую Claude Desktop обычно подавляет.
  • Проверьте это. features.db создаётся рядом с database.py. Если изменится рабочая директория, путь относительно скрипта в get_db_path() Именно это и спасает вас.

7. Заключение

Вот и всё: а FastMCP сервер, хранилище на основе SQLite и конфигурация Claude Desktop, указывающая на него uv run команда. Тот же синтаксис применим ко всему, что можно обернуть в функцию на Python. Заменив вызовы SQLite на настоящий хранилище функций, внутренний API или реестр модель, размер сервера останется небольшим.

Основные выводы

1. MCP представляет собой границу интерфейса инструмента, а не основание для открытия доступа ко всем внутренним функциям.
2. Инструменты сервера следует делать компактными, типизированными и удобными для тестирования без использования LLM.
3. Используйте uv, чтобы можно было заново собрать среду обучения с нуля.
4. Как только агент сможет вызывать MCP сервер, его следует рассматривать как код, предназначенный для продакшена.

Список литературы

• репозиторий этого примера из учебного пособия
• Введение в MCP
• MCP Python SDK
• Claude Desktop
• UV