Перестаньте создавать пользовательские API для ваших ИИ-агентов.

Используйте это как упрощённую версию идей из статьи «Перестаньте писать собственные API для ваших ИИ-агентов: создайте сервер MCP за 5 минут» для операторов: чёткие этапы, структурированные блоки кода и записи по восстановлению, которые сохраняются при передаче задачи. Обзор работает лучше всего, когда рассматривается как измеримая структура. Соберите один идеальный пример работы, один случай сбоя и записи по возврату к предыдущему состоянию перед расширением объёма работы. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. Когда какой-то шаг сбивается, причина сбоя должна указывать на конкретную ответственность, а не на запутанную цепочку операций.

Шаг 1: Архитектура и предварительные требования

Для шага 1: «Архитектура и предварительные требования» необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Укажите названия результатов работы, определите критерии успеха и не допускайте молчаливого частичного завершения задачи. Проводите аутентификацию на шлюзе и повторно предоставляйте разрешения на уровне обработки данных. Одного лишь токена-носителя недостаточно для обозначения границы тенантности.

pip install mcp

Шаг 2: Создание сервера MCP

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

import sqlite3
import json
import os
import sys
from mcp.server.mcpserver import MCPServer

# Initialize the MCP server
mcp = MCPServer(name="Enterprise_SQL_Agent")

# Force the database to be created in the exact same folder as this script
BASE_DIR = os.path.dirname(os.path.abspath(__file__))
DB_PATH = os.path.join(BASE_DIR, "enterprise.db")

def setup_dummy_db():
    """Create a sample employee database for the demo"""
    try:
        conn = sqlite3.connect(DB_PATH)
        cursor = conn.cursor()

        cursor.execute('''CREATE TABLE IF NOT EXISTS employees
                          (id INTEGER PRIMARY KEY, name TEXT, role TEXT, salary INTEGER)''')
        cursor.execute("DELETE FROM employees")

        employees = [
            ("Alice", "Data Scientist", 120000),
            ("Bob", "DevOps Engineer", 115000),
            ("Charlie", "AI Researcher", 135000)
        ]

        cursor.executemany("INSERT INTO employees (name, role, salary) VALUES (?, ?, ?)", employees)
        conn.commit()
        conn.close()
        print("Database initialized successfully.", file=sys.stderr)
    except Exception as e:
        print(f"Database setup error: {e}", file=sys.stderr)

Шаг 3: Обеспечение доступа к базе данных для ИИ

Для шага 3: подключения базы данных к ИИ необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, которое операторы могут проверять, не читая весь кодовый граф. Авторизуйте пользователя у шлюза и повторно предоставляйте права на уровне плоскости данных. Одного только токена не достаточно для обозначения границы аренды. Для шага 3: подключения базы данных к ИИ необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое шага он должен указывать на конкретную причину, а не на запутанную структуру обработки данных.

@mcp.tool()
def query_employee_database(sql_query: str) -> str:
    """
    Executes a SQL SELECT query against the enterprise.db database.

    The database contains an 'employees' table with columns:
    - id (INTEGER PRIMARY KEY)
    - name (TEXT)
    - role (TEXT)
    - salary (INTEGER)

    SECURITY: Only READ operations (SELECT) are permitted.
    """

    # Safety Check: Block destructive SQL commands
    dangerous_keywords = ["DROP", "DELETE", "UPDATE", "INSERT", "ALTER"]
    if any(keyword in sql_query.upper() for keyword in dangerous_keywords):
        return "Error: Only SELECT queries are authorized for this tool."

    try:
        conn = sqlite3.connect(DB_PATH)
        cursor = conn.cursor()
        cursor.execute(sql_query)
        results = cursor.fetchall()

        # Format the output as JSON so the LLM can read it cleanly
        column_names = [description[0] for description in cursor.description]
        formatted_results = [dict(zip(column_names, row)) for row in results]

        conn.close()
        return json.dumps(formatted_results, indent=2)

    except Exception as e:
        return f"Database error: {str(e)}"

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

Шаг 4: Подключение Claude Desktop

При выполнении шага 4: Подключение Claude Desktop сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список поможет избежать ошибок при последующих изменениях кода. Рассматривайте этот этап как договор между входными данными и проверенными результатами. Дайте названия элементам кода, определите критерии успешности и не допускайте безответственного частичного выполнения задачи. Фиксируйте название инструмента, хеш аргументов, время задержки и результат каждого вызова. Без такой записи отладка циклов агента занимает много времени.

{
  "mcpServers": {
    "enterprise-sql": {
      "command": "C:\\Users\\YourName\\.conda\\envs\\your_env\\python.exe",
      "args": [
        "D:\\Your\\Project\\Path\\mcp_server.py"
      ]
    }
  }
}

Шаг 5: Результаты

При работе над шагом 5: Оценка эффективности сначала запишите условия контракта: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой список поможет избежать ошибок при последующих изменениях кода. Рядом с функциональными результатами записывайте время выполнения и стоимость токенов или запросов. Отслеживание затрат с самого начала предотвращает неожиданные расходы при переходе с демо-среды в общедоступные среды. Для каждого вызова фиксируйте название инструмента, хеш аргументов, время задержки и результат. Без такой информации отладка циклов агента занимает много времени.

Что дальше?

При работе над планом дальнейших действий сначала запишите «контракт»: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список помогает сохранять честность при последующих изменениях кода. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Фиксируйте название инструмента, хеш аргументов, время задержки и результат каждого вызова. Без такой записи отладка занимает часы. При работе над планом дальнейших действий сначала запишите «контракт»: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список помогает сохранять честность при последующих изменениях кода. Предпочитайте небольшие, тестируемые единицы кода большим скриптам. Если какой-то шаг не сработает, причина должна быть связана с одной конкретной функцией, а не с запутанной цепочкой операций.

Чек-лист для эксплуатации

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

Документируйте одновременно обычный путь выполнения и путь восстановления. Повторные попытки, проверки со стороны человека и обработка неработоспособных сообщений являются частью продукта, а не элементами последующей доработки.

Зафиксируйте название инструмента, хеш аргументов, время задержки и результат каждого вызова. Без такой записи отладка агента занимает часы.

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

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

Записывайте временные показатели и стоимость токена или запроса рядом с функциональными результатами. Отслеживание затрат на раннем этапе предотвращает неожиданные счета при переходе с демо-среды в общедоступные среды.

Перед тем как запускать стек в продакшен, заморозьте версии, сделайте «золотой» отчет для критического пути и уточните шаги возврата к предыдущей версии. В совместных средах необходимы ограничения по частоте запросов, проверки принадлежности пользователя и четко определенный ответственный за обновление секретов. Лучше выбирать надежность, даже если она кажется скучной, чем креативные одноразовые демонстрации.

Примечание для aed9f8a61db3: не храните ключи поставщика в репозитории, установите лимит токенов на сессию и сохраняйте отчеты рядом с фикстурами для оценки, чтобы последующие замены моделей оставались сопоставимыми.