MCP-сервер Agent-Commerce-OS

Официальный сервер протокола контекста модели (MCP) для инфраструктуры нормализации данных Sakutto Works.

🚀 Обзор

Этот репозиторий предоставляет официальный MCP-сервер для проекта GHOST SHIP (Agent-Commerce-OS). Он позволяет ИИ-агентам (таким как Claude Desktop) автономно подключаться к нашей сети с нулевым доверием (Zero-Trust) и тарификацией через Polar.sh. Благодаря этой интеграции агенты могут извлекать и нормализовать неструктурированные веб-данные в чистые, оптимизированные для токенов форматы Markdown или JSON.

Related MCP server: deltav-edge-mcp-server

✨ Ключевые особенности

• 🛡️ Безопасность периметра с нулевым доверием: Строгая защита от инъекций промптов и защита периметра на границе Cloudflare.

• 🧩 Нативная поддержка MCP: Мгновенная и бесшовная интеграция с клиентами протокола контекста модели, такими как Claude Desktop.

• ⚡ Легкая фильтрация GraphQL: Передайте необязательный массив fields, чтобы извлечь только те узлы данных, которые нужны вашему агенту, что значительно сокращает потребление токенов контекстного окна.

• 💳 Чистая модель оплаты по факту использования: $0.10 за успешный вызов через Polar.sh. Никаких скрытых платежей, никаких принудительных подписок.

• 🤖 Автономное восстановление после ошибок: Строгое соблюдение стандартного форматирования ошибок MCP (isError: true). Интеллектуальная передача ошибок 402 Payment Required и 429 Too Many Requests от пограничного шлюза, что позволяет ИИ-агентам автономно направлять пользователей для устранения нехватки бюджета или остановки бесконечных циклов без вмешательства разработчика.

• 🔍 Распределенная трассировка и наблюдаемость: Каждому запросу присваивается уникальный trace_id, который распространяется по всей инфраструктуре (шлюз -> движок -> журналы аудита R2). В случае ошибки этот Trace ID внедряется непосредственно в текстовый ответ агента, что позволяет мгновенно проводить точечную отладку и обеспечивать поддержку корпоративного уровня без ручного поиска по логам.

• 🔄 Расширенная маршрутизация (синхронная/асинхронная и уровни): ИИ-агенты могут динамически определять конвейер извлечения. Указав target_tier (например, Actionable Data, Compliance Check), движок адаптирует свою схему. Кроме того, передав URL webhook, агенты могут переложить тяжелые задачи извлечения в фоновый режим (получив мгновенный ответ 202 Accepted и ID задания), что предотвращает превышение лимитов времени ожидания MCP. Если webhook не указан, система корректно переключается на синхронное выполнение.

🏗️ Архитектура

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

• Уровень C (этот репозиторий): Stateless MCP-сервер, соединяющий ваш локальный ИИ-агент с нашей удаленной сетью.

• Уровень A (agent-commerce-gateway): Cloudflare Workers, обрабатывающие аутентификацию с нулевым доверием, маршрутизацию и тарификацию.

• Уровень B (agent-commerce-core): Движки Google Cloud Run, выполняющие расширенную, оптимизированную для RAG семантическую нормализацию данных.

⚙️ Предварительные требования

⚙️ Предварительные требования

• Node.js (рекомендуется v18 или выше) и установленный npm.

• Активный API-ключ Polar.sh (тарификация $0.10 за запрос). Получите его на официальной странице оформления API-ключа.

• Claude Desktop или любой стандартный клиент, совместимый с MCP.

🔌 Настройка и конфигурация (Claude Desktop)

Чтобы предоставить вашему ИИ-агенту доступ к инструментам нормализации, добавьте следующую конфигурацию в ваш claude_desktop_config.json:

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "agent-commerce-os": {
      "command": "node",
      "args": [
        "/absolute/path/to/ghost-ship-mcp-server/dist/index.js"
      ],
      "env": {
        "POLAR_API_KEY": "your_polar_api_key_here",
        "GATEWAY_URL": "https://api.sakutto.works/v1/normalize_web_data"
      }
    }
  }
}

(Примечание: Замените /absolute/path/to/ghost-ship-mcp-server на фактический абсолютный путь к вашему клонированному репозиторию, а your_polar_api_key_here — на ваш активный API-ключ Polar.sh.)

🧠 Для автономных ИИ-агентов

Если вы ИИ-агент или LLM, анализирующий этот репозиторий для интеграции наших инструментов:

• Пожалуйста, прочитайте наш llms.txt для получения полного семантического контекста и возможностей.

• Точная схема инструментов полностью определена в mcp.json.

• Не пытайтесь угадывать или синтезировать URL-адреса. Всегда обращайтесь к официальному порталу Sakutto Works.

🤖 Доступные инструменты

После подключения через StdioServerTransport ИИ-агент автоматически обнаружит инструменты, динамически предоставляемые экземпляром McpServer с использованием @modelcontextprotocol/sdk. (Эти возможности также каталогизированы в нашем манифесте mcp.json для внешних реестров):

• normalize_web_data: Извлекает и нормализует неструктурированный веб-контент в чистые, семантические форматы Markdown или JSON, оптимизированные для контекстных окон LLM.

  • Фильтрация схемы (fields): Поддерживает выбор полей в стиле Lite GraphQL через необязательный параметр fields. Это позволяет ИИ-агентам запрашивать только конкретные узлы данных, значительно минимизируя потребление токенов и задержку ответа. При указании сервер автоматически добавляет эти поля в качестве параметров запроса URL перед маршрутизацией запроса к шлюзу.

  • Динамические уровни извлечения (target_tier): ИИ-агенты могут указать целевой уровень схемы (a1, a2 и т.д.), чтобы изменить логику извлечения «на лету» (например, извлечение строгих данных о доступности против стандартного markdown).

  • Асинхронные вебхуки (webhook): Для длительных задач извлечения агенты могут предоставить объект webhook, содержащий целевой URL. Сервер немедленно вернет job_id, позволяя агенту продолжать операции, не дожидаясь завершения. Отказоустойчивый дизайн: Если агент оставляет URL вебхука пустым или полностью пропускает его, сервер безопасно игнорирует полезную нагрузку вебхука и выполняет запрос синхронно, возвращая извлеченные данные в режиме реального времени.

  • Строгая валидация: Все входные данные инструментов строго определены и проверяются с использованием zod, что обеспечивает надежное соблюдение спецификаций Уровня B. После проверки сервер безопасно передает запрос на шлюз через HTTP POST, аутентифицированный с помощью вашего POLAR_API_KEY.

💻 Локальная разработка и настройка

Чтобы запустить сервер локально или подготовить среду для разработки:

1. Клонируйте репозиторий и перейдите в директорию:

   git clone https://github.com/SakuttoWorks/ghost-ship-mcp-server.git
   cd ghost-ship-mcp-server

2. Установите необходимые зависимости (включая @modelcontextprotocol/sdk и zod):

   npm install

3. Настройте переменные окружения:

   cp .env.example .env

   (Откройте созданный файл .env, вставьте ваш POLAR_API_KEY и убедитесь, что GATEWAY_URL установлен на https://api.sakutto.works или конкретный путь конечной точки, например https://api.sakutto.works/v1/normalize_web_data.)

4. Скомпилируйте исходный код TypeScript:

   npm run build

5. Запустите MCP-сервер:

   npm start

🤝 Участие в разработке

Мы приветствуем и поощряем вклад сообщества с открытым исходным кодом! При отправке Pull Request, пожалуйста, убедитесь, что:

• Ваш код успешно собирается (npm run build).

• Все тесты проходят локально (используя npx vitest или ваш предпочтительный тестовый раннер).

• Вы придерживаетесь существующего стиля кода и стандартных практик TypeScript.

Пожалуйста, обратите внимание, что этот проект следует стандартному Кодексу поведения Open Source. Ожидается, что при участии вы будете поддерживать уважительное и совместное общение.

🌍 Ресурсы и отслеживание проблем

• Официальный портал и документация для агентов: Sakutto Works

• GitHub-организация: SakuttoWorks

• Профиль разработчика: SakuttoWorks Profile

• Отчеты об ошибках и запросы функций: Пожалуйста, используйте нашу страницу GitHub Issues для сообщения об ошибках или предложения новых возможностей извлечения.

📄 Лицензия

Этот проект лицензирован по лицензии ISC. Для получения более подробной информации об ответственности и использовании автономных агентов, пожалуйста, прочитайте наш LEGAL.md.

💖 Поддержка проекта

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

© 2026 Sakutto Works. Стандартизация семантической паутины для агентной экономики.