Skip to content
PilotOpenToolsPublic

About

MCP-сервер для работы с Pilot

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

6 stars

Watchers

2 watching

Forks

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.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.

About

MCP-сервер для работы с Pilot

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

6 stars

Watchers

2 watching

Forks

Releases

Packages

Contributors

Languages