Свои системы для агента: MCP, хуки и первые многошаговые процессы

// npm i @modelcontextprotocol/sdk zod
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "orders", version: "1.0.0" });

server.registerTool(
  "get_order_status",
  {
    title: "Статус заказа",
    description: "Возвращает статус заказа по номеру. Номер — целое число из личного кабинета, например 1042.",
    inputSchema: { orderId: z.number().int().positive() },
  },
  async ({ orderId }) => {
    const status = await findStatus(orderId); // ваш запрос к базе или API
    if (!status) {
      return { content: [{ type: "text", text: `Заказ ${orderId} не найден` }], isError: true };
    }
    return { content: [{ type: "text", text: JSON.stringify({ orderId, status }) }] };
  },
);

// stdout занят протоколом: логи пишем только в stderr
await server.connect(new StdioServerTransport());

# pip install mcp
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("orders")

@mcp.tool()
def get_order_status(order_id: int) -> dict:
    """Возвращает статус заказа по номеру. Номер — целое число из личного кабинета."""
    status = find_status(order_id)  # ваш запрос к базе или API
    if status is None:
        raise ValueError(f"Заказ {order_id} не найден")
    return {"order_id": order_id, "status": status}

if __name__ == "__main__":
    mcp.run()  # по умолчанию транспорт stdio

<?php
// composer require php-mcp/server — сторонний пакет, сверьте API с его README
use PhpMcp\Server\Attributes\McpTool;
use PhpMcp\Server\Server;
use PhpMcp\Server\Transports\StdioServerTransport;

final class OrderTools
{
    /**
     * Возвращает статус заказа по номеру.
     */
    #[McpTool(name: 'get_order_status', description: 'Статус заказа по номеру из личного кабинета')]
    public function getOrderStatus(int $orderId): array
    {
        $status = findStatus($orderId); // ваш запрос к базе или API
        if ($status === null) {
            throw new InvalidArgumentException("Заказ $orderId не найден");
        }
        return ['orderId' => $orderId, 'status' => $status];
    }
}

$server = Server::make()->withServerInfo('orders', '1.0.0')->build();
$server->discover(basePath: __DIR__, scanDirs: ['src']);
$server->listen(new StdioServerTransport());

// Без SDK: stdio — это JSON-сообщения, по одному в строке.
// Функцию handle(request) вы напишете в песочнице ниже.
import readline from "node:readline";

const rl = readline.createInterface({ input: process.stdin });
rl.on("line", (line) => {
  let request;
  try { request = JSON.parse(line); }
  catch { return; }
  const response = handle(request);          // null для уведомлений без id
  if (response) process.stdout.write(JSON.stringify(response) + "\n");
});
// console.log сломает протокол: для логов — console.error (stderr)

// .claude/hooks/guard.js — читает событие из stdin, код 2 = запрет
let raw = "";
process.stdin.on("data", (c) => (raw += c));
process.stdin.on("end", () => {
  const event = JSON.parse(raw);
  const input = event.tool_input || {};
  const text = input.command || input.file_path || "";

  const rules = [
    [/\brm\s+-[a-z]*r[a-z]*f|\brm\s+-[a-z]*f[a-z]*r/, "rm -rf запрещён. Удаляйте конкретные файлы."],
    [/(^|[\s\/])\.env(\s|$)/, "Чтение .env запрещено: там секреты. Используйте .env.example."],
    [/git\s+push\b.*(--force|-f)\b/, "Force push запрещён. Попросите человека."],
  ];
  for (const [re, reason] of rules) {
    if (re.test(text)) {
      process.stderr.write(reason);   // это увидит модель
      process.exit(2);                // 2 = заблокировать действие
    }
  }
  process.exit(0);
});

#!/usr/bin/env php
<?php
// .claude/hooks/guard.php
$event = json_decode(stream_get_contents(STDIN), true, flags: JSON_THROW_ON_ERROR);
$input = $event['tool_input'] ?? [];
$text = $input['command'] ?? $input['file_path'] ?? '';

$rules = [
    '~\brm\s+-[a-z]*r[a-z]*f|\brm\s+-[a-z]*f[a-z]*r~' => 'rm -rf запрещён. Удаляйте конкретные файлы.',
    '~(^|[\s/])\.env(\s|$)~' => 'Чтение .env запрещено: там секреты.',
    '~git\s+push\b.*(--force|-f)\b~' => 'Force push запрещён. Попросите человека.',
];
foreach ($rules as $re => $reason) {
    if (preg_match($re, $text)) {
        fwrite(STDERR, $reason);
        exit(2);
    }
}
exit(0);

#!/usr/bin/env python3
# .claude/hooks/guard.py
import json
import re
import sys

event = json.load(sys.stdin)
tool_input = event.get("tool_input", {})
text = tool_input.get("command") or tool_input.get("file_path") or ""

RULES = [
    (r"\brm\s+-[a-z]*r[a-z]*f|\brm\s+-[a-z]*f[a-z]*r", "rm -rf запрещён. Удаляйте конкретные файлы."),
    (r"(^|[\s/])\.env(\s|$)", "Чтение .env запрещено: там секреты."),
    (r"git\s+push\b.*(--force|-f)\b", "Force push запрещён. Попросите человека."),
]
for pattern, reason in RULES:
    if re.search(pattern, text):
        print(reason, file=sys.stderr)
        sys.exit(2)
sys.exit(0)