
pilotmcp
io.github.PilotOpenTools/pilotmcp
MCP server for ASCON Pilot-ICE PDM: objects, documents, remarks, search, admin
Documentation

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.mcpb | MCP 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_URL | URL сервера, например 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 |
GetChangesets | Changesets в диапазоне 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.
https://github.com/PilotOpenTools/PilotMCP/releases/download/v0.1.1/PilotMCP-v0.1.1-win-x64.mcpb# mcpb: https://github.com/PilotOpenTools/PilotMCP/releases/download/v0.1.1/PilotMCP-v0.1.1-win-x64.mcpb