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-клиента:
| Переменная | Описание | Обязательная |
|---|---|---|
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 |
Пароль администратора сервера | нет |
{
"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) |
Инструменты, помеченные *, требуют учётную запись администратора сервера
(PILOT_ADMIN_LOGIN / PILOT_ADMIN_PASSWORD) — см. раздел «Редактирование метаданных» ниже.
Блокируются режимом PILOT_READONLY.
| Инструмент | Описание |
|---|---|
CreatePerson |
Создать пользователя (логин, имя, пароль, признак администратора) * |
UpdatePersonAdmin |
Изменить логин, имя, пароль, isAdmin, активность * |
DeletePerson |
Пометить пользователя удалённым * |
CreateOrgUnit |
Создать оргединицу: Department / Position / Group * |
UpdateOrgUnit |
Изменить название оргединицы, признак руководителя * |
DeleteOrgUnit |
Пометить оргединицу удалённой (если нет живых дочерних) * |
MoveOrgUnits |
Перенести оргединицы к новому родителю * |
SetPersonOnPosition |
Назначить пользователя на должность * |
RemovePersonFromPosition |
Освободить должность * |
Особенности сервера, выявленные тестами: новый пользователь не сможет войти, пока не назначен
на должность (SetPersonOnPosition); должности не могут находиться в корне оргструктуры —
только внутри отдела.
| Инструмент | Описание |
|---|---|
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); нужен один из двух |
Модель может читать, анализировать, редактировать и создавать отчёты в формате 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.
