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

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

🚀 Обзор

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

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

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

Уровень C (этот репозиторий): MCP-сервер без сохранения состояния, соединяющий ваш локальный ИИ-агент с нашей удаленной сетью.
Уровень A (agent-commerce-gateway): Cloudflare Workers, отвечающие за аутентификацию с нулевым доверием, маршрутизацию и тарификацию.
Уровень B (agent-commerce-core): Движки Google Cloud Run, выполняющие расширенную семантическую нормализацию данных, оптимизированную для RAG.

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

Активный API-ключ Polar.sh (тарификация $0.10 за запрос). Получите свой ключ на официальной странице оформления заказа.
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"
      }
    }
  }
}

(Примечание: замените /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 перед отправкой запроса на шлюз.
- Строгая проверка: Все входные данные инструментов строго определены и проверяются с помощью zod, что обеспечивает надежное соблюдение спецификаций Уровня B. После проверки сервер безопасно передает запрос на шлюз через HTTP POST, используя аутентификацию с помощью вашего POLAR_API_KEY.

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

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

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

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

Установите необходимые зависимости (включая @modelcontextprotocol/sdk и zod):
```
npm install
```
Настройте переменные окружения:
```
cp .env.example .env
```
(Откройте созданный файл .env, вставьте свой POLAR_API_KEY и убедитесь, что GATEWAY_URL установлен на https://api.sakutto.works или конкретный путь к конечной точке, например https://api.sakutto.works/v1/normalize_web_data.)
Скомпилируйте исходный код TypeScript:
```
npm run build
```
Запустите MCP-сервер:
```
npm start
```

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

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

Ваш код успешно собирается (npm run build).
Все тесты проходят локально (с использованием npx vitest или вашего предпочтительного средства запуска тестов).
Вы придерживаетесь существующего стиля кода и стандартных практик TypeScript.

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

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

📄 Лицензия

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

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

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

SakuttoWorks-Data-Normalizer