Repository avatar
Search & Data Extraction
v0.1.1
active

pilotmcp

io.github.PilotOpenTools/pilotmcp

MCP server for ASCON Pilot-ICE PDM: objects, documents, remarks, search, admin

Documentation

PilotMCP

PilotMCP

MCP-сервер для работы с Pilot через Server API. Позволяет LLM-агентам подключаться к серверу Pilot, выполнять поиск, создавать и изменять объекты, работать с документами, историей изменений, правами доступа и чатами.

Документация: https://pilotopentools.github.io/PilotMCP/ · DeepWiki: https://deepwiki.com/PilotOpenTools/PilotMCP

Требования

  • .NET 8.0
  • Доступ к серверу Pilot

Установка

Подробнее об установке и настройке клиентов — в документации.

Готовые сборки (Windows x64) — на странице Releases:

ФайлДля чего
PilotMCP-vX.Y.Z-win-x64.mcpbMCP Bundle: установка в Claude Desktop в один клик, параметры подключения вводятся в форме
PilotMCP-vX.Y.Z-win-x64-selfcontained.zipРаспаковать и указать PilotMCP.exe в конфигурации клиента; .NET не нужен
PilotMCP-vX.Y.Z-win-x64.zipТо же, но нужен установленный .NET 8 Runtime

Сервер также опубликован в официальном MCP Registry под именем io.github.PilotOpenTools/pilotmcp.

Выпуск релиза

Релиз собирается GitHub Actions по тегу вида vX.Y.Z (semver, допускается суффикс -beta.1):

git tag vX.Y.Z
git push origin vX.Y.Z

Workflow release.yml прогоняет unit-тесты, собирает zip-архивы и .mcpb, создаёт GitHub Release и публикует server.json в MCP Registry (вход по OIDC, секреты не нужны). Версия берётся из тега. Манифест бандла — mcpb/manifest.json. Вместо vX.Y.Z подставьте новую версию, которой ещё нет среди тегов. CHANGELOG в репозитории не ведётся: описание релиза GitHub создаёт автоматически (--generate-notes). Подробности, включая ограничения release.yml, — в docs/development.md.

На push в любую ветку и на pull request ci.yml собирает проект и прогоняет unit-тесты (на ветке с открытым PR он запускается дважды). Интеграционные тесты (Category=Integration) требуют живой сервер Pilot и запускаются локально: dotnet test PilotMCP.slnx с параметрами своего сервера: скопируйте шаблон PilotMCP.Tests/test.runsettings в PilotMCP.Tests/test.local.runsettings (он в .gitignore, подхватывается автоматически) и заполните.

Подключение к MCP-клиенту

Параметры подключения задаются через переменные окружения в конфигурации MCP-клиента:

ПеременнаяОписаниеОбязательная
PILOT_SERVER_URLURL сервера, например http://localhost:5545/u_db_nameда
PILOT_LOGINЛогин пользователяда
PILOT_PASSWORDПароль пользователяда
PILOT_DATABASEИмя базы данных (если пусто — берётся из URL)нет
PILOT_LICENSE_TYPEКод лицензии: по умолчанию 100нет
PILOT_READONLYРежим только чтения: true или 1. Блокирует все операции записи.нет
PILOT_ADMIN_LOGINЛогин администратора сервера — для инструментов редактирования метаданных (автоматизации, типы, состояния). Если не задан, используется PILOT_LOGIN.нет
PILOT_ADMIN_PASSWORDПароль администратора серверанет

Пример конфигурации (LM Studio, Ollama, Claude Code, Cursor и т.д.)

{
  "mcpServers": {
    "pilot": {
      "command": "C:\\path\\to\\PilotMCP.exe",
      "env": {
        "PILOT_SERVER_URL": "http://localhost:5545/u_db_name",
        "PILOT_LOGIN": "username",
        "PILOT_PASSWORD": "password",
        "PILOT_DATABASE": "",
        "PILOT_LICENSE_TYPE": "103",
        "PILOT_READONLY": "false"
      }
    }
  }
}

Надёжность записи

  • Операции записи через Modifier/Backend (создание и изменение объектов, связей, задач, замечаний и т.д.) дожидаются ответа сервера (до 60 с). Отказ сервера возвращается как ошибка с его текстом; по таймауту сообщается, что результат неизвестен.
  • При обрыве соединения PilotMCP переподключается и повторяет только читающие вызовы. Записи после таймаута или обрыва автоматически не повторяются, чтобы не создать дубликаты, — проверьте состояние и повторите вручную.
  • Метаданные перечитываются, когда сервер сообщает об их изменении; параллельные изменения метаданных внутри одного процесса PilotMCP выполняются последовательно.

Режим только чтения

При PILOT_READONLY=true сервер сообщает модели об ограничениях через системный промпт при инициализации. Модель не будет пытаться выполнять операции записи и сразу сообщит пользователю об ограничении.

Заблокированы: CreateObject, SetAttribute, DeleteObject, RestoreObject, MoveObject, LockObject, UnlockObject, FreezeObject, UnfreezeObject, MakeSecret, MakePublic, DeleteFile, SetUserState, Subscribe, Unsubscribe, AnnotateText, CreateAnnotation, CreateMarkupAnnotation, SendMessage, EditMessage, ReplyMessage, CreateChat, UploadFile, InvokeCommand, CreateLink, DeleteRelation, AddAccessRecord, RemoveAllAccessRecords, UpdatePerson, ChangeSettings, CreateReport, UpdateReport, CreateTask, CreateWorkflow, AddSignatureRequest, CreateAutomationConfig, UpdateAutomationConfig, DeleteAutomationConfig, CreateType, UpdateType, DeleteType, AddTypeChildren, AddTypeAttribute, UpdateTypeAttribute, DeleteTypeAttribute, CreateUserState, UpdateUserState, DeleteUserState, CreateStateMachine, UpdateStateMachine, DeleteStateMachine, CreatePerson, UpdatePersonAdmin, DeletePerson, CreateOrgUnit, UpdateOrgUnit, DeleteOrgUnit, MoveOrgUnits, SetPersonOnPosition, RemovePersonFromPosition.


Архитектура

Bulk-инструменты (поиск, дочерние объекты и т.п.) записывают результаты во временные JSONL-файлы, а не возвращают данные напрямую в контекст. Это позволяет работать с тысячами объектов без перегрузки контекста модели.

Search("проект") → {resultFile: "tmp/search_x.jsonl", count: 8543}
     ↓
FilterObjects("tmp/search_x.jsonl", "typeName", "document") → tmp/filter_x.jsonl (85 записей)
     ↓
ExportCsv("tmp/filter_x.jsonl", "C:/result/docs.csv", "name,typeName,created")

Формат промежуточных файлов — JSONL (JSON Lines): один JSON-объект на строку.


Инструменты

Подключение

ИнструментОписание
GetDatabaseInfoИнформация о текущей базе данных и подключённом пользователе

Объекты

ИнструментОписание
GetObjectПолучить объект по GUID: все атрибуты, файлы, связи, права, состояние
GetAttributeПрочитать полное значение одного атрибута без обрезки (когда GetObject обрезал значение)
GetTypeИнформация о типе объекта по системному имени
GetTypesВсе типы объектов базы → JSONL-файл
CreateObjectСоздать объект (родитель, тип, атрибут; значение разбирается по типу атрибута, неизвестный атрибут — ошибка)
SetAttributeУстановить значение атрибута объекта (значение разбирается по типу атрибута: числа/даты в инвариантном формате; неизвестный атрибут — ошибка)
DeleteObjectУдалить объект (в корзину)
RestoreObjectВосстановить объект из корзины
MoveObjectПереместить объект в другую папку
LockObjectЗаблокировать объект (эксклюзивное редактирование); только из состояния Alive
UnlockObjectРазблокировать объект; только из LockRequested/LockAccepted
FreezeObjectЗаморозить объект (запретить редактирование); только из состояния Alive
UnfreezeObjectРазморозить объект (разрешить редактирование); только из состояния Frozen
MakeSecretСделать объект секретным (ограниченный доступ)
MakePublicСнять секретность с объекта
SetUserStateУстановить пользовательское состояние (UserState) на объекте
SubscribeПодписаться на уведомления об изменениях объекта
UnsubscribeОтписаться от уведомлений об изменениях объекта
DownloadFileСкачать файл из Pilot на диск (через .part: существующий файл не затирается при сбое; пустое содержимое — ошибка)
UploadFileЗагрузить файл с диска в объект: новая версия, прежние файлы сохраняются, одноимённый заменяется
DeleteFileУдалить файл из объекта по его Body.Id
GetFileSizeРазмер файла в архиве Pilot по Body.Id (считается чтением по частям, без сохранения на диск; пустой/несуществующий — ошибка)
ComputeFileMd5Вычислить MD5-хэш файла из архива Pilot (по Body.Id) или локального файла

Навигация и поиск

ИнструментОписание
SearchКомбинированный поиск → JSONL-файл. Некорректные фильтры (GUID, даты, атрибут) — ошибка, а не более широкий поиск
SearchByTextПолнотекстовый поиск; спецсимволы Lucene (: ( ) " - и др.) ищутся буквально
SearchInContextПоиск объектов внутри папки (рекурсивно по всем вложенным)
SearchByTypeПоиск объектов по типу (typeId из GetTypes)
SearchByAttributeПоиск по значению СТРОКОВОГО атрибута (фраза из нескольких слов — одним термом)
SearchByStateПоиск объектов по пользовательскому состоянию (UserState)
SearchByCreatorПоиск объектов по создателю (personId)
SearchByDateДиапазон дат создания (ISO 8601, UTC; to без времени включает весь день; пустая граница — открытая)
GetAllObjectsПолучить все объекты базы (поиск в контексте корня)
GetChildrenДочерние объекты по GUID → JSONL-файл (при недоступных объектах пишет «загружено X из Y»)
GetRootObjectsКорневые объекты базы → JSONL-файл
GetObjectsToFileНесколько объектов по списку GUID → JSONL-файл
GetUserStatesСписок пользовательских состояний (UserStates) — для задач и workflow
GetStateMachinesМашины состояний (StateMachines) — workflow и переходы между состояниями

Пользователи и организация

ИнструментОписание
GetPeopleВсе пользователи (email, phone, accountState и т.д.) → JSONL-файл
GetOrganisationUnitsВсе оргединицы (kind, person, иерархия) → JSONL-файл
GetPeopleByIdsПодробная информация о пользователях по списку ID
GetOrgUnitsByIdsПодробная информация об оргединицах по списку ID
GetPersonOnPositionУзнать кто занимает указанную позицию (по positionId)
UpdatePersonОбновить email, phone, comment, isInactive пользователя по personId (админский API)

Управление пользователями и оргструктурой (админский API)

Инструменты, помеченные *, требуют учётную запись администратора сервера (PILOT_ADMIN_LOGIN / PILOT_ADMIN_PASSWORD) — см. раздел «Редактирование метаданных» ниже. Блокируются режимом PILOT_READONLY.

ИнструментОписание
CreatePersonСоздать пользователя (логин, имя, пароль, признак администратора) *
UpdatePersonAdminИзменить логин, имя, пароль, isAdmin, активность *
DeletePersonПометить пользователя удалённым *
CreateOrgUnitСоздать оргединицу: Department / Position / Group *
UpdateOrgUnitИзменить название оргединицы, признак руководителя *
DeleteOrgUnitПометить оргединицу удалённой (если нет живых дочерних) *
MoveOrgUnitsПеренести оргединицы к новому родителю *
SetPersonOnPositionНазначить пользователя на должность *
RemovePersonFromPositionОсвободить должность *

Особенности сервера, выявленные тестами: новый пользователь не сможет войти, пока не назначен на должность (SetPersonOnPosition); должности не могут находиться в корне оргструктуры — только внутри отдела.

Работа с файлами результатов (pipe-инструменты)

ИнструментОписание
ExtractFieldsИзвлечь выбранные поля из JSONL → новый JSONL (отсутствующее поле = null). outputFile не может совпадать с inputFile (во всех инструментах записи)
FilterObjectsОтфильтровать записи по значению поля → новый JSONL
ExtractFieldToTextИзвлечь одно поле построчно в текстовый файл
PreviewFileПросмотреть N записей из файла (до 20)
ReadFileПрочитать текстовый файл (или его часть) с пагинацией через offset/limit (отрицательный offset = 0)
CountFileКоличество записей в файле
ExportCsvЭкспортировать JSONL в CSV (колонки по умолчанию — объединение ключей всех записей)
SaveResultСкопировать файл результатов в указанное место

Документы и аннотации

ИнструментОписание
GetDocumentTextИзвлечь текст документа (XPS или PDF) для анализа; число страниц берётся из файла, page вне диапазона — ошибка, для документа без текстового слоя (скан) сообщается об этом; maxChars действует и на превью
FindTextOnPageНайти все вхождения текста и получить координаты; пустой searchText — ошибка. Единицы: XPS — 1/96 дюйма, PDF — пункты (1/72 дюйма), y — верх текста сверху вниз (указаны в ответе)
ExtractPageTextИзвлечь все текстовые блоки со страницы с координатами → JSONL (единицы те же, что у FindTextOnPage)
GetDocumentPageImageПолучить изображение страницы документа (PDF или XPS); dpi 36-300, длинная сторона не больше 2000 px (при превышении dpi снижается, фактический указан в ответе), page вне диапазона — ошибка; PNG сохраняется в %TEMP%\pilot-mcp и удаляется через сутки
AnnotateTextЗамечание к слову/фразе (XPS или PDF): style = highlight (по умолчанию), underline, strikeout
CreateAnnotationГрафическое замечание: rectangle, ellipse, triangle, arrow, line, polyline, polygon, ink, point; параметры strokeWidth, points (x1,y1;x2,y2;...), cloud, startEnding/endEnding
CreateMarkupAnnotationОДНО замечание из нескольких фигур: shapesJson — JSON-массив с полями как у CreateAnnotation
GetAnnotationsПрочитать замечания документа (формат markup/legacy, фигуры, страница, прямоугольник в пикселях, автор, версия файла); замечания из корзины пропускаются; нечитаемое замечание выводится с полем error
BuildAnnotationXmlСгенерировать XML-разметку аннотации в старом (legacy) формате без создания объекта

Формат замечаний. По умолчанию AnnotateText, CreateAnnotation и CreateMarkupAnnotation создают замечания в формате Markup (клиент Pilot 26.20+: атрибуты markups и markups_version). Параметр format=legacy (AnnotateText, CreateAnnotation) создаёт замечание в старом формате (атрибут annotation) для серверов и клиентов старше 26.20; новые фигуры и параметры в нём недоступны. Координаты фигур — в пикселях изображения от GetDocumentPageImage (тот же dpi); размеры страниц берутся из того же файла (XPS, иначе PDF). Окончания линий: none, openarrow (у arrow по умолчанию openarrow на острие).

История и версии

ИнструментОписание
GetHistoryИстория изменений объектов по списку GUID
GetChangesetsChangesets в диапазоне ID (номер, identity, GUID изменённых; не более 1000 номеров)

Права доступа

ИнструментОписание
CheckAccessПроверить уровень доступа пользователя к объекту
CheckAccessByUnitПроверить уровень доступа организационной единицы к объекту
GetAccessRecordsЗаписи прав доступа для объекта (кому и какие)
AddAccessRecordДобавить запись прав доступа к объекту
RemoveAllAccessRecordsУдалить все ограничения доступа (сделать объект публичным)
GetObjectsWithRightsОбъекты с информацией о правах текущего пользователя (до 20 записей прав на объект; некорректный GUID — ошибка)
GetSubscribersПодписчики объекта (personIds пользователей)

Связи между объектами

ИнструментОписание
CreateLinkСоздать двустороннюю связь между двумя объектами (дубликат с тем же типом и именем не создаётся; допустимы только перечисленные типы)
DeleteRelationУдалить связь между объектами

Чаты

ИнструментОписание
GetChatsСписок чатов текущего пользователя
GetChatИнформация о конкретном чате (тип, описание, связи, непрочитанные); несуществующий чат — ошибка
GetPersonalChatЛичный чат с пользователем по personId (ошибка, если чата ещё нет; инструмент его не создаёт)
GetChatMembersУчастники чата (роли, статусы уведомлений)
CreateChatСоздать групповой чат
GetMessagesСообщения чата, skip=0 — самые новые; skip растёт назад по истории. Правки показываются с пометкой (ред.), реакции и markdown помечаются
GetMessageОдно сообщение по GUID (автор, дата, тип, текст)
SearchMessagesПоиск сообщений по тексту в указанных или (при пустом chatIds) во всех чатах пользователя; некорректный GUID — ошибка
GetRelatedChatsЧаты, связанные с объектом (обсуждение задачи/документа)
SendMessageОтправить сообщение в чат
EditMessageРедактировать ранее отправленное сообщение
ReplyMessageОтветить на конкретное сообщение в чате
CheckOnlineПроверить онлайн-статус пользователя

Настройки

ИнструментОписание
GetPersonalSettingsПерсональные настройки пользователя по разделу
GetCommonSettingsОбщие настройки базы
ChangeSettingsИзменить настройку пользователя (personId) или оргединицы (orgUnitId); нужен один из двух

Отчёты (.repx)

Модель может читать, анализировать, редактировать и создавать отчёты в формате DevExpress XtraReports. Скрипты в отчётах используют C# 4 и Pilot Report API (ReportContext, QueryBuilder, RObject).

ИнструментОписание
FindReportsНайти папку отчётов и показать все отчёты (рекурсивно) с GUID
GetReportПрочитать .repx из объекта Pilot (для анализа или правки)
UpdateReportОбновить .repx в существующем объекте
CreateReportСоздать новый отчёт с .repx в указанной папке
ListReportSamplesСписок доступных примеров отчётов
GetReportSampleПрочитать конкретный пример (с API-справкой)

Автоматизации

Модель может читать, анализировать автоматизации. В т.ч. их С# код.

ИнструментОписание
GetAutomationConfigsВсе автоматизации, включая их основную часть и C# код → JSONL-файл
CreateAutomationConfigСоздать автоматизацию (имя, триггеры, C# код) *
UpdateAutomationConfigИзменить автоматизацию по имени (код, триггеры, пауза) *
DeleteAutomationConfigУдалить автоматизацию по имени *
ValidateAutomationScriptПроверить C# код автоматизации на сервере без сохранения *

Редактирование метаданных (типы, атрибуты, состояния)

Инструменты, помеченные *, работают через админский API сервера (как Pilot-myAdmin): требуется учётная запись администратора сервера (PILOT_ADMIN_LOGIN / PILOT_ADMIN_PASSWORD; если не заданы — используются основные логин/пароль). Каждая операция читает свежие метаданные, вносит точечное изменение и записывает их обратно целиком, поэтому параллельные правки в myAdmin не затираются. Все операции блокируются в режиме PILOT_READONLY.

ИнструментОписание
CreateTypeСоздать тип объекта (вид, файлы, монтируемость, родительские типы) *
UpdateTypeИзменить тип (название, файлы, сортировка, машина состояний) *
DeleteTypeПометить пользовательский тип удалённым (IsDeleted) и убрать его из Children родителей *
AddTypeChildrenДобавить дочерние типы (какие типы можно создавать внутри) *
AddTypeAttributeДобавить атрибут к типу (Integer, String, DateTime, OrgUnit, ...) *
UpdateTypeAttributeИзменить атрибут типа *
DeleteTypeAttributeУдалить атрибут типа *
CreateUserStateСоздать пользовательское состояние (цвет, признак завершения) *
UpdateUserStateИзменить пользовательское состояние *
DeleteUserStateПометить состояние удалённым (если не используется в машинах) *
CreateStateMachineСоздать машину состояний с переходами (JSON) *
UpdateStateMachineИзменить машину состояний (название, полная замена переходов) *
DeleteStateMachineУдалить машину состояний (если не привязана к типам) *

Задачи

ИнструментОписание
CreateTaskСоздать задачу (тип с префиксом 'task_'). deadline — yyyy-MM-dd, срок до 23:59:59 этого дня; некорректные deadline, attachmentIds (в т.ч. несуществующие объекты) и attributes дают ошибку
CreateWorkflowСоздать пустой workflow (тип с префиксом 'workflow_', без стадий); инициатор по умолчанию — первая позиция пользователя

Подписи

ИнструментОписание
AddSignatureRequestДобавить запрос на подпись к файлу в объекте (имя файла не найдено — ошибка)

Прочее

ИнструментОписание
InvokeCommandВызвать команду серверного расширения Pilot Server (только заранее зарегистрированные команды); ждёт и возвращает результат до 15 с

Сборка релиза

dotnet build -c Release

Релизная сборка дополнительно кладёт в artifacts/ два готовых архива под win-x64:

АрхивРазмерТребования на машине пользователя
PilotMCP-v<версия>-win-x64-selfcontained.zip~75 МБничего, .NET внутри
PilotMCP-v<версия>-win-x64.zip~43 МБустановленный .NET 8 Runtime

В каждом архиве — PilotMCP.exe со всеми зависимостями, папка ReportSamples, README.md, LICENSE, THIRD-PARTY-NOTICES.md и папка licenses с текстами лицензий сторонних компонентов. Отладочные символы (.pdb) исключены.

Версия берётся из <Version> в PilotMCP.csproj, платформа — из свойства ReleaseRid там же.

Собрать только архивы, без прочих проектов решения:

dotnet build PilotMCP.csproj -c Release

Отключить упаковку (например, в CI, где нужна только сборка):

dotnet build -c Release -p:SkipReleasePackaging=true

Лицензия

Проект распространяется по лицензии Apache 2.0. В релизные архивы входят сторонние библиотеки на своих условиях, в том числе MuPDFCore под AGPL-3.0: см. THIRD-PARTY-NOTICES.md.

Участие

Issues и PR приветствуются. Перед отправкой PR убедитесь, что проект собирается. Правила участия: CONTRIBUTING. Кодекс поведения: CODE_OF_CONDUCT.

MCPB
https://github.com/PilotOpenTools/PilotMCP/releases/download/v0.1.1/PilotMCP-v0.1.1-win-x64.mcpb
Install Command
# mcpb: https://github.com/PilotOpenTools/PilotMCP/releases/download/v0.1.1/PilotMCP-v0.1.1-win-x64.mcpb