Припиніть створювати власні API для ваших AI-агентів

Використовуйте цей матеріал як оновлену версію ідей з статті „Перестаньте писати власні API для ваших AI-агентів: створіть сервер MCP за 5 хвилин“ для спеціалістів-операторів: чіткі етапи, впорядковані блоки коду та примітки з відновлення, які залишаються при передачі обов’язків. Огляд ефективніше всього функціонує, якщо його розглядати як вимірювану поверхню. Запишіть один ідеальний запис, один випадок збою та примітки щодо скасування змін перед розширенням обсягу роботи. Віддавайте перевагу невеликим, тестованим одиницям коду перед об’ємними скриптами. Коли якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність дій.

Крок 1: Архітектура та передумови

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

pip install mcp

Крок 2: Створення сервера MCP

Для кроку 2: створення сервера 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: не зберігайте ключі постачальника у репозиторії, встановіть ліміт токенів на сеанс та зберігайте записи поруч із фікстурами для оцінки, щоб подальша заміна моделей залишалася порівнянною.