Перейти к основному содержимому

MCP-сервер

Этот документ был подготовлен при помощи ИИ

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

В Architeezy встроен сервер Model Context Protocol: через него ИИ-агент работает с моделями напрямую. Агенту доступны список проектов, чтение модели и её метамодели, запись изменений, создание представлений и перемещение блоков на диаграммах.

Конечная точка и аутентификация​

Сервер использует транспорт Streamable HTTP по пути /mcp на том же хосте, что и приложение, — https://architeezy.com/mcp в облачном сервисе.

Конечная точка доступна только аутентифицированным клиентам. Клиенту, который поддерживает удалённые серверы с OAuth, не нужно ничего, кроме URL: он находит сервер авторизации по метаданным защищённого ресурса на /.well-known/oauth-protected-resource, а тот принимает динамическую регистрацию клиентов. Клиент без поддержки OAuth отправляет в заголовке bearer токен доступа, выпущенный для публичного клиента architeezy-api.

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

Настройка клиентов​

Claude Code​

Добавьте сервер, а затем выполните /mcp внутри Claude Code, чтобы завершить вход по OAuth:

claude mcp add --transport http architeezy https://architeezy.com/mcp

Visual Studio Code​

Опишите сервер в файле .vscode/mcp.json вашего рабочего пространства или откройте пользовательскую конфигурацию командой MCP: Open User Configuration:

{
  "servers": {
    "architeezy": {
      "type": "http",
      "url": "https://architeezy.com/mcp"
    }
  }
}

При первом подключении VS Code откроет браузер для входа и подтверждения доступа.

Cursor​

Опишите сервер в файле .cursor/mcp.json в проекте или в ~/.cursor/mcp.json, чтобы он был доступен везде:

{
  "mcpServers": {
    "architeezy": {
      "url": "https://architeezy.com/mcp"
    }
  }
}

Приложения Claude​

На claude.ai откройте Customize → Connectors, нажмите +, выберите Add custom connector и введите https://architeezy.com/mcp. Вход по OAuth выполняется при подключении, после чего коннектор доступен в приложениях Claude, вошедших в ту же учётную запись. Серверы Anthropic обращаются к конечной точке от вашего имени, поэтому сервер в частной сети таким способом недоступен.

Соглашения инструментов​

Постраничная выдача. Каждый список принимает page (начиная с 0) и size (по умолчанию 50, максимум 500) и отвечает полем items вместе с блоком page:

{
  "items": [],
  "page": { "size": 50, "number": 0, "totalElements": 30, "totalPages": 1 }
}

Сортировка. sort принимает field,direction, например name,asc. Несколько условий разделяются символом ;.

Фильтрация. filter — объект JSON, где значение каждого ключа — массив. Элементы массива — альтернативы; * в начале или конце значения задаёт совпадение по префиксу, суффиксу или подстроке без учёта регистра; ведущий ! переворачивает условие.

{
  "name": ["Order*", "Payment*"],
  "project.id": ["019b2a78-5fa0-728a-b861-e51b5ad26984"]
}

Инструменты​

Пространства моделирования и проекты​

listScopes возвращает контейнеры верхнего уровня, в которых может находиться проект, с признаками, сообщающими агенту, вправе ли он там что-либо создавать. listProjects перечисляет доступные вам проекты, а createProject добавляет проект в пространство моделирования по имени. listImportedProjects обходит замыкание зависимостей проекта — именно так агент находит метамодели и общие модели, на которых построен проект.

Модели​

listAllowedModelKinds перечисляет типы моделей, которые можно создать в проекте. В список попадают типы, определённые в самом проекте, типы из импортируемых им проектов и типы из любого другого доступного вам проекта-метамодели. Значение id — то, что ожидает createModel; если тип пришёл из ещё не импортированного проекта, импорт добавится сам.

listModels находит модели; readModel возвращает одну из них в виде дерева содержимого. Передайте objectId, чтобы прочитать поддерево отдельного объекта вместо всей модели, и depth, чтобы остановиться на заданном уровне вложенности. Большую модель дешевле читать по частям, чем целиком.

readMetamodel возвращает метамодель, стоящую за моделью, в компактном виде: классификаторы, их супертипы, их признаки с типом и кратностью, а также литералы перечислений. Агент читает её перед записью, чтобы отправлять существующие имена классов и признаков.

updateModel применяет патч, deleteModel удаляет модель вместе с её содержимым.

Объекты​

deleteObjects удаляет объекты из модели одним атомарным пакетом. Удаление идёт каскадом по композиции: потомки удаляемого объекта тоже удаляются и перечисляются в ответе. Если на удаляемые объекты ссылаются из других мест проекта, удаление по умолчанию не выполняется, а ссылки перечисляются в ответе; с аргументом deleteIncomingReferencesInProject очищаются те ссылки, которые очистить безопасно. Обязательную одиночную ссылку Architeezy не очищает никогда.

Представления​

listRepresentationDescriptions перечисляет типы представлений, которые можно создать для данного объекта; createRepresentation создаёт представление по идентификатору описания. listRepresentations находит существующие представления и возвращает идентификаторы, нужные инструментам работы с диаграммами, вместе с URL, открывающим каждое из них в браузере. deleteRepresentation удаляет представление, не затрагивая модель.

Раскладка диаграммы​

readDiagramLayout возвращает геометрию диаграммы: дерево узлов с их children и borderNodes и плоский список рёбер. Координаты задаются относительно ближайшего родительского узла. У каждого узла и каждого ребра есть targetObjectId, поэтому агент может перейти от блока на диаграмме к стоящему за ним объекту с помощью readModel.

updateDiagramLayout записывает позиции и размеры обратно, объединяя их по id. Он двигает и меняет размеры того, что уже есть на диаграмме, но узлов не создаёт и не удаляет и не соглашается сменить узлу родителя. Пустой path ребра возвращает автоматическую маршрутизацию.

Патчи модели​

updateModel принимает частичное дерево содержимого и сливает его с моделью. Каждая запись называет объект по id, его тип в виде <prefix>:<EClass> и признаки, которые вы задаёте в data:

  • Значение id вида tmp:<name> создаёт новый объект. Тот же tmp:<name>, поставленный строковым значением в другом месте того же патча, укажет на этот новый объект.
  • Массивы композиции сливаются по id, поэтому указание одного потомка добавляет или обновляет именно его, не затрагивая соседей. Добавьте целочисленный ordinal, чтобы поместить потомка в заданную позицию.
  • Массивы множественных ссылок заменяются целиком, поэтому отправляйте полный нужный вам список.
  • Значение ссылки записывается как <uuid> внутри модели, <modelId>#<uuid> для другой модели в том же проекте и <prefix>:<EClass> <modelId>#<uuid> в полной канонической форме.

Патч применяется целиком либо не применяется вовсе; отклонённый патч оставляет модель ровно такой, какой она была.

Два необязательных аргумента делают запись безопасной для повторения:

  • idempotencyKey — тот же ключ с тем же телом возвращает первый ответ вместо повторного применения изменения. Тот же ключ с другим телом — ошибка.
  • expectedLastModificationDateTime — отметка времени, которую агент увидел при чтении модели. Если с тех пор кто-то ещё выполнил запись, обновление отклоняется, а не затирает чужую работу.

Передавайте returnContent: "none", когда агенту не нужно получать дерево обратно после применения патча.

Пример: добавление элемента и размещение его на диаграмме​

Архитектор просит агента: добавь компонент приложения Billing Service в модель ArchiMate в проекте Showcase, сделай так, чтобы он обслуживал Ordering Service, и помести его на диаграмму.

1. Найти модель.

listModels { "filter": "{\"project.id\":[\"019b2a78-5fa0-728a-b861-e51b5ad26984\"]}" }
{
  "items": [
    {
      "id": "019b2b46-fc08-795b-8929-4179a5ea98b9",
      "name": "ArchiMate",
      "type": "http://www.archimatetool.com/archimate#ArchimateModel",
      "url": "https://architeezy.com/demo/showcase/dev/archimate",
      "lastModificationDateTime": "2025-12-18T13:04:29.984441Z"
    }
  ]
}

2. Изучить словарь. readMetamodel для пространства имён http://www.archimatetool.com/archimate подтверждает, что ApplicationComponent и ServingRelationship существуют, что Folder хранит своё содержимое в elements, а у связи есть source и target.

3. Понять, куда что помещать. readModel с depth: 2 возвращает корень модели и её папки. В ответе есть идентификаторы папок Application и Relations, а также идентификатор существующего элемента Ordering Service.

4. Записать изменение.

updateModel {
  "id": "019b2b46-fc08-795b-8929-4179a5ea98b9",
  "expectedLastModificationDateTime": "2025-12-18T13:04:29.984441Z",
  "returnContent": "none",
  "data": {
    "content": [
      {
        "id": "9abb47b3-0704-5e36-a76f-dde1426c31f2",
        "eClass": "archimate:Folder",
        "data": {
          "elements": [
            {
              "id": "tmp:billing",
              "eClass": "archimate:ApplicationComponent",
              "data": { "name": "Billing Service" }
            }
          ]
        }
      },
      {
        "id": "c9192668-0b87-563b-87c0-4550c3586d7c",
        "eClass": "archimate:Folder",
        "data": {
          "elements": [
            {
              "id": "tmp:serves",
              "eClass": "archimate:ServingRelationship",
              "data": {
                "source": "tmp:billing",
                "target": "d569ff64-e964-587e-8125-82769c66c7f9"
              }
            }
          ]
        }
      }
    ]
  }
}

В ответе приходят идентификаторы, присвоенные двум записям tmp:.

5. Поместить на диаграмму. Блок на представлении ArchiMate — это потомок представления типа DiagramModelArchimateObject, указывающий на элемент, поэтому агент патчит представление точно так же:

{
  "content": [
    {
      "id": "4332d237-8569-5b74-99f6-c6167a4afa0f",
      "eClass": "archimate:ArchimateDiagramModel",
      "data": {
        "children": [
          {
            "id": "tmp:billing-box",
            "eClass": "archimate:DiagramModelArchimateObject",
            "data": { "archimateElement": "<id assigned to tmp:billing>" }
          }
        ]
      }
    }
  ]
}

6. Разместить. readDiagramLayout показывает, где что расположено:

{
  "diagramId": "019b2b47-2baa-7cf6-810f-592119ba5a3b",
  "modelId": "019b2b46-fc08-795b-8929-4179a5ea98b9",
  "nodes": [
    {
      "id": "1b533efc-...",
      "label": "Ordering Service",
      "x": 472,
      "y": 307,
      "width": 137,
      "height": 55
    },
    {
      "id": "b92d6557-...",
      "label": "Web Store System",
      "x": 472,
      "y": 420,
      "width": 137,
      "height": 55
    }
  ],
  "edges": [
    {
      "id": "9d9ada7e-...",
      "sourceNodeId": "b92d6557-...",
      "targetNodeId": "1b533efc-...",
      "path": []
    }
  ]
}

Затем агент вызывает updateDiagramLayout с идентификатором нового узла и координатами свободного места рядом с Ordering Service. Блок появляется на диаграмме у всех, у кого она открыта.