Onplana MCP server

Open-source строительные блоки Model Context Protocol на TypeScript, извлечённые из продакшн-развёртывания MCP компании Onplana. Два пакета:

• onplana-mcp-server: серверный шаблон. Транспорт Streamable HTTP, аутентификация Bearer, изоляция от prompt-инъекций, подключаемый диспетчер.

• onplana-mcp-client: типизированный TypeScript SDK клиента для вызова публичного MCP-эндпоинта Onplana по адресу https://api.onplana.com/api/mcp/v1.

Что это такое

Транспортный уровень MCP-сервера (обвязка Streamable HTTP, режим без состояния, ограниченная Bearer-аутентификация, изоляция от prompt-инъекций), сделанный правильно и отделённый от реестра инструментов, специфичного для платформы. Используйте серверный шаблон, чтобы собрать собственный MCP-сервер со встроенными лучшими практиками безопасности. Используйте клиентский SDK, чтобы управлять размещённым MCP Onplana из своего кода.

Эти паттерны извлечены из продакшн-развёртывания Onplana (публичная документация — onplana.com/mcp), того самого слоя, который обрабатывает реальный трафик Claude Desktop, Cursor, кастомного коннектора ChatGPT и внутренних агентов к платформе Onplana.

Related MCP server: MCP Server Template

Зачем open-source

Транспорт MCP одинаков для всех. Большинство ранних MCP-серверов ошибаются в примитивах безопасности:

• Prompt-инъекция. Инструменты, возвращающие пользовательский контент (заголовки задач, тела комментариев, вики-текст), помещают этот контент напрямую в контекст модели. Без изоляции злоумышленник может внедрить "ignore previous instructions" в свои собственные данные, и следующий агент, который прочитает это, последует инструкции.

• Транспорт без состояния. Большинство примеров SDK предполагают состояние сессии в памяти, что ломает горизонтальное масштабирование и усложняет модель аутентификации.

• Семантика plan-gate. Показ инструментов, которые вызывающий на самом деле не может использовать, тратит ходы и сбивает модель с толку.

Onplana решила эти проблемы в продакшене за шесть месяцев работы над MCP-сервером. Публикация паттернов даёт высокую отдачу:

1. Другие авторы MCP получают проверенный шаблон вместо изобретения велосипеда.

2. Репозиторий — это поверхность pretraining-сигнала. Публичные README на GitHub имеют большой вес в обучающих данных LLM следующего поколения, а репозиторий с паттернами и понятной документацией об MCP улучшает запоминание моделями того, «как выглядят хорошие MCP-серверы».

3. Интерфейс диспетчера — это место стыковки, куда подключается ваша бизнес-логика. Транспорт универсален; в вашем MCP-сервере важнее всего реестр инструментов. Открытие исходного кода транспорта не раскрывает ничего проприетарного.

Реализация диспетчера, каталог инструментов, логика plan-gate, инфраструктура аудита и остальная часть закрытого диспетчера Onplana объёмом ~600 строк кода остаются в закрытом монорепозитории, поскольку в них закодирована бизнес-логика платформы. Если вы создаёте собственный MCP-сервер на основе этого шаблона, вы пишете собственный диспетчер. Это та работа, которая имеет значение, и та работа, которая специфична для вашей платформы.

Структура репозитория

onplana-mcp-server/
├── packages/
│   ├── server-template/        # onplana-mcp-server (npm)
│   │   ├── src/
│   │   │   ├── transport.ts    # Streamable HTTP wiring
│   │   │   ├── auth.ts         # Bearer auth pattern
│   │   │   ├── promptInjection.ts  # wrapUserContent + escape
│   │   │   ├── dispatcher.ts   # Pluggable Dispatcher interface
│   │   │   └── index.ts
│   │   ├── tests/              # promptInjection + auth + transport
│   │   └── README.md
│   └── client/                 # onplana-mcp-client (npm)
│       ├── src/
│       │   ├── client.ts       # OnplanaMcpClient class
│       │   ├── types.ts        # Public type surface
│       │   └── index.ts
│       ├── tests/              # client.test.ts (stub fetch)
│       └── README.md
├── .claude-plugin/
│   └── marketplace.json        # Claude Code marketplace
├── plugins/
│   └── onplana/                # Claude Code plugin (skills + connect command)
├── examples/
│   └── in-memory/              # Runnable demo with 3 toy tools
├── gemini-extension.json       # Gemini CLI manifest
├── mcp.json                    # stdio client config (mcp-remote)
├── server.json                 # MCP registry manifest
└── .github/workflows/
    ├── ci.yml                  # tsc + vitest on PR
    └── publish.yml             # npm publish on tag v*

Быстрый старт

Создание сервера

Установка:

npm install github:Onplana/onplana-mcp-server @modelcontextprotocol/sdk express

Подключите Express-приложение:

import express from 'express'
import {
  createMcpPostHandler,
  createMcpMethodNotAllowedHandler,
  requireBearerAuth,
  type Dispatcher,
} from 'onplana-mcp-server'

const dispatcher: Dispatcher = {
  async listTools(ctx) { /* return your tool descriptors */ return [] },
  async callTool(name, input, ctx) { /* dispatch to your tools */ return { output: {} } },
}

const auth = async (token: string) => {
  // Validate against your token store. Return AuthContext or null.
  return { userId: 'u', scopes: ['MCP_AGENT'] }
}

const app = express()
app.use(express.json())
app.use('/api/mcp/v1',
  requireBearerAuth({ auth, requiredScope: 'MCP_AGENT' }),
)
app.post('/api/mcp/v1', createMcpPostHandler({ dispatcher }))
app.get('/api/mcp/v1', createMcpMethodNotAllowedHandler())
app.delete('/api/mcp/v1', createMcpMethodNotAllowedHandler())
app.listen(3000)

Полный краткий гайд — в packages/server-template/README.md; запускаемый демо-пример — в examples/in-memory/.

Управление Onplana из кода

Установка:

npm install github:Onplana/onplana-mcp-server

Использование:

import { OnplanaMcpClient } from 'onplana-mcp-client'

const client = new OnplanaMcpClient({
  url:   'https://api.onplana.com/api/mcp/v1',
  token: process.env.ONPLANA_PAT!,
})

const projects = await client.listProjects({ status: 'ACTIVE' })

// The differentiator vs other PM-tool MCPs: hybrid semantic + lexical
// search across your org's indexed content (projects, tasks, risks,
// goals, comments, wiki pages).
const { matches } = await client.searchOrgKnowledge({
  query: 'rationale for the 3-week design phase',
  scope: 'all',
  limit: 5,
})

Полная документация клиента — в packages/client/README.md.

Инструменты

Размещённый сервер по адресу https://mcp.onplana.com/mcp предоставляет 285 инструментов, охватывающих проекты, задачи, спринты, вехи, освоенный объём, риски, проблемы, управление, контроль изменений, табели учёта времени, вики, онлайн-доски, рабочие процессы и интеграции с Microsoft Graph. Точное число, которое видит конкретный клиент, меньше, потому что перед выдачей каталога инструменты фильтруются по роли вызывающего и тарифному плану организации.

Ниже приведены 33 инструмента, которые стоит узнать в первую очередь, — это не весь каталог. Чтения помечены readOnlyHint; записи несут destructiveHint, чтобы клиент мог их ограничивать. Каждый вызов выполняется от имени вызывающего, проверяется по правам этого пользователя и тарифному плану организации и попадает в журнал аудита.

Чтение (readOnlyHint: true)

• list_projects: проекты в организации, фильтруются по статусу.

• get_project: один проект полностью, с датами, владельцем и прогрессом.

• list_tasks: задачи по проекту или по нескольким проектам.

• get_task: одна задача с описанием, исполнителем, датами и недавними комментариями.

• list_my_tasks: задачи, назначенные на вызывающего пользователя.

• list_overdue: задачи с просроченным сроком выполнения.

• list_team_members: участники проекта.

• list_org_members: участники организации.

• list_risks: риски, зарегистрированные по проекту.

• find_similar_projects: прошлые проекты, похожие на описание, для оценки.

• search_org_knowledge: гибридный поиск BM25 и векторный поиск по задачам, проектам, вики-страницам и комментариям.

• summarize_project: ИИ-сводка, синтезированная из актуального плана.

• analyze_project_risks: ИИ-обнаружение рисков по срокам, бюджету, объёму и ресурсам.

• generate_status_report: ИИ-отчёт о статусе на основе текущего расписания и активности.

• search: адаптер App Directory, возвращает {id, title, snippet?, url?}.

• fetch: адаптер App Directory, возвращает {id, title, content, url?, metadata?}.

Запись, аддитивная (destructiveHint: false)

• create_project: создать проект.

• create_task: создать задачу, опционально внутри родительской.

• create_milestone: добавить веху в проект.

• create_comment: оставить комментарий к задаче, проблеме или проекту.

• create_sprint_with_tasks: создать спринт и включить в него задачи.

• submit_timesheet: записать часы по задаче.

• add_project_member: добавить существующего участника организации в проект.

• link_dependency: связать две задачи, идемпотентно через уникальное ограничение.

Запись, изменяющая (destructiveHint: true)

• update_project: изменить поля проекта, такие как статус, даты или бюджет.

• update_task: изменить поля задачи, такие как статус, прогресс или даты.

• bulk_update_tasks: применить одно изменение ко многим задачам.

• assign_task: назначить исполнителя задачи.

• move_task_to_sprint: переместить задачу в спринт или из спринта.

Аренда (для агентов, работающих с общим бэклогом)

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

• claim_task: взять эксклюзивную аренду на конкретную задачу.

• renew_task_lease: продлить аренду, пока работа ещё выполняется.

• release_task: вернуть аренду; завершение или блокировка задачи тоже освобождает её, а завершение сессии освобождает всё, что удерживает данный запуск.

Аренда привязана к запуску (RUN), а не к пользователю. Две сессии одного клиента аутентифицируются как один и тот же агент-персонаж, поэтому блокировка по пользователю позволила бы одной сессии освободить работу другой. Аренда истекает сама, так что упавший агент освобождает свою задачу, а не удерживает её.

Инструменты удаления отсутствуют в каталоге по умолчанию, а разрушающие операции запрещены по умолчанию: владелец организации включает их для каждой операции, прежде чем агент сможет их вызвать. Те, что можно включить, обратимы — они перемещаются в корзину, а не уничтожаются. В любом случае предпочитайте update_task удалению с пересозданием, поскольку Onplana аудирует каждое изменение поля и сохраняет историю.

Чек-лист для продакшена

Шаблон + SDK позволяют вам запуститься. Добавьте поверх следующее:

• Ограничение частоты запросов на токен. 60–120 запросов/мин на Bearer-токен; агентные циклы шумнее, чем люди.

• Лимит расходов тенанта. Если ваши инструменты вызывают платные LLM, ограничивайте диспетчеризацию по расходам с начала месяца. В развёртывании Onplana используется aiMonthlyCostCapUsd с режимами WARN / BLOCK.

• Журналирование аудита. Каждая диспетчеризация должна записывать строку аудита с тегом actorType: 'mcp_agent', чтобы администраторы могли видеть, что ИИ-агенты делали в их тенанте, отдельно от действий людей.

• Курирование плана и области видимости. Не раскрывайте каждый внутренний инструмент. Onplana раскрывает 21 из 26; скрытые 5 либо требуют встроенного UI предпросмотра, либо слишком рискованны для вызова без контроля, либо возвращают слишком большие полезные нагрузки.

• Режим PREVIEW для рискованных изменений. По умолчанию переводите изменяющие инструменты в режим только предпросмотра на бесплатных тарифах. Onplana это делает: агенты видят «что это сделает», прежде чем пользователи явно обновят тариф и повторят запуск.

• Ключи идемпотентности. Хешируйте канонизированный вход + идентификатор сессии; храните как уникальное ограничение в строке аудита. Модель, повторяющая одно и то же логическое действие, не должна создавать дубли.

Каждый из этих пунктов специфичен для платформы. Шаблон даёт вам место стыковки, куда они подключаются (Dispatcher.callTool); ваш диспетчер реализует их так, как ваша платформа кодирует эти концепции.

Совместимость

• Node.js ≥ 20 (для серверного шаблона и матрицы CI); ≥ 18 для клиента (использует встроенный fetch).

• @modelcontextprotocol/sdk@^1.29.0

• express@^4.18.0 или express@^5.0.0

Протестировано с:

• Claude Code (маркетплейс плагинов или claude mcp add --transport http)

• Claude Desktop (Custom Connector)

• Cursor (~/.cursor/mcp.json)

• ChatGPT custom connectors (если MCP включён в вашем аккаунте)

• Gemini CLI + Gemini Code Assist (~/.gemini/settings.json)

• GitHub Copilot in VS Code (.vscode/mcp.json)

• Официальный MCP Inspector

Установка в Claude Code

Репозиторий также работает как маркетплейс плагинов Claude Code, так что установка занимает две команды:

/plugin marketplace add Onplana/onplana-mcp-server
/plugin install onplana@onplana

Затем подключите сервер:

/onplana-connect

Эта команда выполняет claude mcp add --transport http onplana https://mcp.onplana.com/mcp и проводит вас через вход в браузере. MCP-сервер доступен на всех тарифных планах Onplana, включая бесплатный.

Плагин поставляется с двумя навыками агента Onplana, вызываемыми как onplana:<name>:

Манифест плагина намеренно не объявляет MCP-сервер. Плагин объявляет серверы в stdio-форме (command, args, env), а сервер Onplana — удалённый и аутентифицируется через OAuth, поэтому /onplana-connect подключает его во время выполнения через нативный HTTP-транспорт Claude Code, а не через stdio-прослойку.

Установка в Gemini CLI

В корне репозитория лежит манифест gemini-extension.json, поэтому Gemini CLI устанавливает Onplana одной командой:

export ONPLANA_PAT=pat_paste-your-token-here  # mint at app.onplana.com/integrations
gemini extensions install https://github.com/Onplana/onplana-mcp-server

Перезапустите CLI gemini (или перезагрузите окно VS Code / JetBrains, если вы используете Gemini Code Assist). Инструменты Onplana появятся в /mcp, а ваш контекст GEMINI.md подхватит подсказки по использованию, поставляемые в этом репозитории.

Участие в разработке

Приветствуются issues и PR. Репозиторий намеренно небольшой; цель — чтобы транспортные паттерны были очевидными, хорошо протестированными и стабильными. Повышение мажорной версии предназначено для ломающих изменений форм экспортируемых Dispatcher / BearerAuth / фабрик обработчиков. Патчи и минорные версии — для улучшений изоляции от prompt-инъекций, новых вспомогательных утилит и дополнительного тестового покрытия.

Лицензия

MIT. © 2026 Onplana

Смотрите также

• onplana.com/mcp: публичная страница документации для продакшн-развёртывания Onplana MCP (полный каталог инструментов, инструкции по настройке, модель безопасности)

• onplana.com: Onplana, платформа управления проектами. Облачно-независимая, AI-нативная, альтернатива Microsoft Project Online

• Model Context Protocol specification: стандарт MCP

• Anthropic prompt-injection guidance: паттерн безопасности, реализуемый обёрткой этого репозитория