NOTA Handbook MCP Server
Внутренний MCP-сервер компании NOTA. Подключается к любому MCP-совместимому LLM-клиенту (Claude Desktop, Claude.ai Connectors, кастомные интеграции) и даёт ему исчерпывающий контекст про компанию: стратегию и прогресс по ней, идентичность и ценности, организационную структуру, активные эксперименты и план.
Endpoint: `https://nota-handbook.pages.dev/api/mcp`
Protocol: Model Context Protocol поверх JSON-RPC 2.0 over HTTP
Server name: `nota-handbook-mcp`
TL;DR
- Что: MCP-сервер, который превращает Notion-корпус NOTA в структурированный набор tools + готовых prompt-команд для LLM.
- Зачем: чтобы Claude / любой другой LLM, подключённый к серверу, мог давать обоснованные ответы про NOTA опираясь на свежие данные, а не на догадки и обрывки прошлой переписки.
- Где живёт: Cloudflare Pages.
- Источник правды: Notion (DBs стратегии, ролей, метрик, ценностей; markdown-страницы /who).
- Свежесть: ежесуточный cron + кнопка «↻ Обновить» в шапке сайта = ручной trigger полной переиндексации.
- Сколько: 30 read tools, 6 write tools, 6 готовых slash-prompts.
Зачем это нужно
LLM по умолчанию ничего не знает про конкретную компанию. Чтобы давать обоснованные ответы про NOTA, нужно одно из:
- Скармливать корпус в каждый чат — дорого по контексту, неудобно, быстро устаревает.
- Полагаться на обучение — знает только то что было в публичных данных до cutoff, ничего внутреннего.
- Дать LLM tools чтобы он сам находил нужное — это и делает MCP.
MCP-сервер NOTA позволяет любому подключённому LLM задавать вопросы вида:
- «Что NOTA делает прямо сейчас? Какая активная ставка?» → `getCurrentBet`, `getStrategyProgress`
- «Как устроена компания? Кто такой Diwan?» → `getCompanyStructure`, `getRole`
- «Объясни ценности NOTA с примерами» → `listValues` + `getValue` (или slash-prompt `explain_values`)
- «Кто отвечает за финансы?» → `findResponsible`
- «Что изменилось в стратегии за последнюю неделю?» → `recentChanges`
- «Найди всё про Digital Shift» → `searchHandbook` (гибрид: семантика + точный текст)
И записывать обратно в Notion:
- «Я только что переговорил с лидом — добавь наблюдение к эксперименту 5 и обнови чекбокс боль подтверждена» → `recordExperimentSignal`
- «Подвинь эксперимент в стадию Запуск с обоснованием» → `advanceExperimentStage`
- «Запиши новый риск к ставке: цикл продаж в MENA длиннее ожидаемого» → `appendBetRisk`
Архитектура
Слои данных
- Notion — единственный источник правды. CEO правит данные напрямую в Notion, никаких копий в коде нет.
- KV cache (`HANDBOOK_CACHE`) — ускоряет доступ к Notion-данным с stale-while-revalidate. TTL подобран по природе данных:
- Vectorize index (`handbook-corpus`) — векторное представление всего корпуса. Embedded через Workers AI с моделью `@cf/baai/bge-m3` (multilingual, 1024 dims). Используется для семантического поиска через `searchHandbook`.
- Сам MCP server — тонкий слой, который маршрутизирует JSON-RPC методы (`initialize`, `tools/list`, `tools/call`, `prompts/list`, `prompts/get`) на handlers.
Как подключить
Вариант 1 — Claude.ai (Web) через Custom Connectors
Самый простой путь для CEO и команды. Работает в браузере, ничего ставить не нужно.
- Открой Claude.ai → Settings → Connectors
- Add custom connector
- Заполни:
- Save → connector появится в списке доступных в чатах
- В новом чате включи NOTA Handbook в списке connectors
- Спроси что-то — Claude автоматически вызовет `getCompanyOverview` и пойдёт дальше
Write-tools (изменяют Notion): для них нужен `MCP_WRITE_TOKEN`. Поскольку Claude.ai не пробрасывает Bearer-токены автоматически, write-tools отключены при анонимном подключении.
Вариант 2 — Claude Desktop через mcp-remote
Claude Desktop из коробки умеет stdio-MCP, для HTTP нужен мост — пакет `mcp-remote`.
- Открой `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) или `%APPDATA%\Claude\claude_desktop_config.json` (Windows).
- Добавь в `mcpServers`:
{
"mcpServers": {
"nota-handbook": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://nota-handbook.pages.dev/api/mcp"
]
}
}
}- Полный рестарт Claude Desktop (Quit, не закрытие окна).
- В чате внизу появится иконка инструментов — `nota-handbook` со списком tools.
- Slash-команды (`/company_overview`, `/strategy_status` и т.д.) появятся в slash-меню.
Если нужны write-tools — добавь header `Authorization: Bearer ${MCP_WRITE_TOKEN}` в `args` через `--header` и положи токен в `env`.
Что даёт после подключения
Точка входа
Любой LLM, подключившийся к серверу свежим, должен сначала вызвать `getCompanyOverview` (это написано в `instructions` поля ответа `initialize`, которое Claude Desktop показывает как системную подсказку). Этот tool возвращает:
- Сегодняшнюю дату (для time-relative запросов)
- Идентичность NOTA: 4 ценности с tagline-ами
- Активную стратегическую ставку: title, статус, confidence, формулировку, даты сверки
- Размер корпуса: сколько тезисов, экспериментов, шагов, профилей клиентов
- Автогенерируемую карту всех 32 tools, сгруппированных по разделам
После этого LLM понимает, куда идти за конкретными вопросами.
Карта всех tools
- `getCompanyOverview` — единая точка входа
- `getStrategyOverview` — короткий обзор активной ставки
- `getStrategyProgress` — синтетический срез: статусы шагов, что идёт сейчас, что застряло, состояние сверки
- `listBets` — все ставки (активная + параллельные)
- `getCurrentBet` — полные данные активной ставки
- `getThesis` — конкретный тезис с source-ами
- `listTheses` — все тезисы по слою (Рыночный сдвиг / Разрыв-окно / Сегмент / ...)
- `getRoadmapStep` — конкретный шаг с подшагами и body
- `listSteps` — фильтрованный список шагов (статус, природа, тип, горизонт, активные сейчас)
- `getExperiment` — PMF-эксперимент целиком
- `listExperiments` — список экспериментов
- `listClientProfiles` — четыре слоя клиентов
- `listSources` — источники с количеством ссылок
- `getSource` — один источник + back-ref на тезисы
- `getQuestionnaire` — активный PMF-опросник
- `getKillSwitches` — критерии опровержения ставки
- `getReviewStatus` — давность сверки, дни до следующей
- `listInterviews` — PMF-интервью с фильтрами по итогу, профилю, окну дат, эпизоду и эксперименту
- `getInterview` — одно интервью со всеми полями и связями
- `getPmfWaveStatus` — срез волны интервью против Switch #1 в одном вызове (целевые числа, скорость, дни до дедлайна, требуемая недельная скорость; цели читаются из 💀 DB)
- `getExperimentEvidence` — для одного эксперимента: связанные интервью + pain/payment-signal агрегаты + days-to-decision
- `listInterviewSignals` — кросс-секционные текстовые фрагменты по размерности (workaround / loss / tried / commitment) с атрибуцией; сырьё для паттерн-анализа, не пытается кластеризовать сам
- `getStrategyGraph` — все DUAL-связи вокруг любой Hub-сущности
- `listWhoPages` — карта раздела «Кто мы»
- `getWhoPage` — полное тело страницы по slug-у (mission / values / decisions / communication / effectiveness / ai / systems-thinking / digital-shift / ...)
- `listValues` — 4 ценности NOTA
- `getValue` — одна ценность: tagline / why / practice / rejects / history / body
- `getCompanyStructure` — иерархия организации
- `listRoles` — все активные роли (фильтры по типу, PAEI)
- `getRole` — роль: продукт должности, заказчик, иерархия, сотрудники, метрики
- `findResponsible` — кто отвечает за тему / роль / имя
- `listMetrics` — метрики оценки (фильтр по EEQ)
- `getMetric` — метрика + кого оценивает
- `searchHandbook(query, mode)` — гибридный поиск по всему корпусу (mode: `hybrid` / `semantic` / `exact`), фильтры по `kind` и `module`
- `recentChanges(days, kind?)` — что обновилось в Notion за N дней по `last_edited_time`
- `updateStepStatus` — поменять статус шага + опциональная заметка
- `recordExperimentSignal` — обновить чекбоксы и/или дописать наблюдение к эксперименту
- `recordInterview` — создать запись в 🗣 DB одним вызовом: автозаголовок «№N YYYY-MM-DD — Респондент», все стандартные properties (Дата, Итог, Эпизод назвал?, Якорный коммитмент, Воркэраунд, Пробовал, Потеря, Коммитмент, Заметки, Read.ai), relations к профилю/экспериментам/ставке/интервьюеру
- `advanceExperimentStage` — двинуть эксперимент по стадиям (Идея → ... → Запуск/Отказ)
- `markBetReviewed` — отметить что сверка прошла
- `appendBetRisk` — добавить риск к активной ставке
Готовые slash-prompts
В Claude Desktop / Claude.ai они появляются как `/`-команды:
Каждый prompt содержит инструкцию какие именно tools вызывать в каком порядке, поэтому первый прогон сразу даёт качественный ответ — LLM не нужно с нуля выводить навигационный граф.
Примеры рабочих сценариев
1. Новый человек в команде разбирается в стратегии
`@nota-handbook /company_overview` → получает миссию, ценности, активную ставку, структуру за один заход.
2. CEO ведёт сверку
`@nota-handbook /strategy_status` → список застрявших шагов, эксперименты с подтверждённой болью, дни до следующей сверки. Дальше: «Зафиксируй риск: MENA фаундеры часто требуют офис в Dubai как условие пилота» → Claude вызывает `appendBetRisk` (с разрешения).
3. Кто-то из C-Suite готовит презентацию
`@nota-handbook Объясни как у нас устроены метрики оценки топ-менеджмента` → Claude → `listMetrics(eeq="Effectiveness")` → `getMetric(...)` для каждой → структурированный ответ с примерами.
4. Партнёр интересуется деталями продукта
`@nota-handbook Что мы продаём в Digital Shift? И какие у нас уже подтверждения от клиентов?` → `searchHandbook("Digital Shift")` → `getCurrentBet` → `listExperiments` → ответ с фактами и ссылками на эксперименты.
Авторизация и безопасность
Read-tools (открытые)
Все 27 read-tools доступны без авторизации. Это сделано осознанно: handbook — внутренний документ компании, но содержит публичную информацию (стратегия, оргструктура, ценности), которой компания так или иначе делится с партнёрами и клиентами.
⚠️ Открытый вопрос: при росте партнёрского канала (ветка #8) часть стратегических данных может стать чувствительной — kill-switches ставки, конкретные риски, цифры по PMF-разговорам. См. в Roadmap пункт «Закрыть Strategy-tools Bearer-ом». Сейчас — оставляем открыто.
Write-tools (Bearer-gated)
5 tools мутируют Notion. Каждый их вызов требует header `Authorization: Bearer ${MCP_WRITE_TOKEN}`. Токен живёт как secret в Cloudflare Pages (нельзя прочитать обратно, только перевыпустить).
Свежесть данных
Цепочка от правки в Notion до видимости в MCP:
- CEO правит Notion → данные изменились в источнике правды.
- KV cache хранит копию данных с TTL 4ч–7д. Пока она не истекла, LLM видит старую версию.
- Vectorize index хранит чанки + embeddings. Пока не переиндексировано — `searchHandbook` в semantic-режиме ищет в старом срезе.
Способ 1 — кнопка «↻ Обновить» в шапке сайта (для CEO, мгновенно по требованию)
Один клик дёргает `/api/refresh` с Bearer токеном. За ~60-120 секунд:
- Чистит все 17 known KV-ключей.
- Переиндексирует ~340 чанков в Vectorize.
- Тост в правом нижнем: `✓ Обновлено · N чанков · Xс`.
После этого следующий запрос к MCP видит свежие данные.
Способ 2 — daily cron (автоматически, ежесуточно)
Внешний cron (GitHub Actions / cron-job.org) дёргает `POST /api/reindex` раз в сутки. Это подстраховка чтобы индекс не уходил в дрейф больше чем на 24 часа без явного обновления.
Note: Cloudflare Pages не поддерживает scheduled functions через next-on-pages, поэтому используем внешний trigger.
Способ 3 — Notion webhook (опционально, мгновенно при правке)
`POST /api/revalidate` принимает webhook от Notion и чистит KV scope-ом (`all` / `strategy` / `who` / `structure` / `values`). Vectorize при этом НЕ перестраивается — для этого нужен `/api/refresh`.
Webhook в Notion на момент написания этого документа не настроен. Это главный пункт ближайшего Roadmap — без него правки в Notion видны MCP с задержкой до 4 часов.
Расходы
На текущем масштабе (~340 чанков, ~10 запросов/день от LLM-агентов):
- Cloudflare Pages — бесплатно (Free tier: 100K requests/day)
- Workers KV — бесплатно (Free tier: 100K reads/day)
- Vectorize — бесплатно (Free tier: 5M vectors stored, 30M queried/month)
- Workers AI — pay-per-token, ~$0.0001 за 1K токенов; полная переиндексация (~340 чанков × ~500 токенов) = $0.02. Запрос на семантический поиск = ~10 input токенов = $0.000001.
- Notion API — бесплатно для нашего объёма
Итог: на сегодня сервер обходится в копейки в месяц. Масштаб до 1000 чанков + 1000 LLM-запросов/день — те же копейки.
Roadmap
Планы на будущее, сгруппированные по приоритету для стратегии. Тех. детали (как добавить новый tool, как деплоить, troubleshooting) живут в README репозитория.
Ближайший приоритет (Q3 2026)
Главный неимплементированный пункт. Сейчас правки в Notion видны MCP с задержкой до 4 часов (TTL для strategy scope). После настройки webhook — задержка ~1 секунда. Это критично для сценария «CEO правит ставку перед звонком с инвестором, через минуту инвестор сам открывает MCP».
Конфигурируется через Notion Integration page → Webhook URL: `https://nota-handbook.pages.dev/api/revalidate` + Bearer header. Vectorize при этом не перестраивается, для этого остаётся кнопка «↻ Обновить».
Сейчас 6 базовых prompts покрывают новых пользователей и общий обзор. Не хватает рабочих инструментов для Дивана:
- `/diwan_review_prep` — готовит срез к квартальной сверке Дивана: активные milestone-точки в статусе «Ждёт решения», шаги с просроченными сроками, эксперименты с датой решения в ближайшие 90 дней
- `/bet_health_check` — проверяет здоровье ставки: давность сверки тезисов, шаги без активности, kill-switches приближаются ли
- `/pmf_signals` — реализовано на уровне tools (см. `getPmfWaveStatus` для агрегата по Switch #1, `getExperimentEvidence` для одного эксперимента, `listInterviewSignals` для кросс-секционного сырья). Slash-prompt можно добавить как тонкую обёртку, но острая нужда снята.
Средний приоритет (Q4 2026 — Q1 2027)
Самый важный недостающий пласт. Когда у NOTA будут платные consultative-проекты (Q3 2026+), MCP должен уметь отвечать на вопросы вида «как идут платные проекты?», «какой следующий milestone у клиента X?». Без этого MCP не покрывает самые важные данные для решений Дивана.
Tools: `listProjects`, `getProject`, `getProjectsByClient`, `getProjectStatus`, `recentProjectUpdates`. Источник — отдельная DB Projects в Notion (нужно создать).
Сейчас все read-tools открыты публично — это допустимо пока handbook-корпус не содержит чувствительной коммерческой информации. По мере того как стратегия наполняется конкретными цифрами (юнит-модель, реальный CAC/LTV, имена потенциальных лицензиатов из переговоров) — часть read-tools должна стать Bearer-gated.
Предлагаемое разделение:
- Открыты остаются: `listValues`, `getValue`, `listWhoPages`, `getWhoPage`, `getCompanyStructure`, `listRoles`, `getRole`, `listMetrics`, `getMetric` — публичная идентичность и структура
- Закрываются Bearer-ом: `getCurrentBet`, `getKillSwitches`, `listExperiments`, `getExperiment`, `getStrategyProgress`, `getThesis`, `listTheses`, `getRoadmapStep`, `listSteps`, `getReviewStatus` — стратегическая чувствительность
Реализация — одна правка в `app/api/mcp/route.ts:tools/call` (по аналогии с write-tools).
Кроме tools и prompts, MCP поддерживает resources (файлы/документы которые клиент может читать на лету). Можно отдавать ключевые Notion-страницы как resources: «Как устроен Strategy Hub», описание ставки, страницы /who. Это снижает количество tool calls для базовых сценариев.
Долгосрочно (2027+)
Workers Analytics Engine, чтобы понимать какие tools реально дёргаются, кем, сколько раз в день. Без этого мы не знаем, какие 32 tool из 32 действительно нужны, а какие — мёртвый груз. К 2027 (когда придёт партнёрский канал #8) эта метрика станет важной для понимания ценности handbook-MCP-как-продукта.
Slack-каналы команды, meeting notes (через Read.AI), email threads. Tools: `recentMeetings`, `searchCommunications`. Это превращает MCP из «навигатора по handbook» в полноценную операционную память компании, которую LLM может опрашивать.
⚠️ Уровень чувствительности здесь резко вырастает — внутренние коммуникации не для публичного access. Эти tools обязательно Bearer-gated.
Гипотеза: при подтверждении ставки (Q3 2027 go/no-go = «Да») handbook-MCP может стать одним из лицензионных продуктов NOTA. Сценарий: «вот ваш собственный handbook-MCP, развёрнутый на вашем Notion + наши лучшие практики структуры handbook + onboarding» — для бизнес-школ, форумов, консалтинговых групп.
Это пока не подтверждённая гипотеза, а запасной актив, который созревает параллельно с основной ставкой.
Schema 🗣 DB — изменения 2026-05-08
В рамках поддержки PMF-инструментов (`getPmfWaveStatus`, `recordInterview`, `getExperimentEvidence`, `listInterviewSignals`) в `🗣 Проблемные интервью` добавлены три property:
- Дата (`date`) — explicit поле с датой интервью. Раньше дата зашивалась в title по конвенции `№N YYYY-MM-DD — …`; теперь это самостоятельное property. Transformer `fromInterviewPage` читает Дата → fallback на ISO scrape из title → fallback на пустую строку, чтобы не сломать legacy entries.
- Интервьюер (`person`) — Notion user, кто провёл разговор. Используется в `getPmfWaveStatus` для секции «По интервьюеру». Опциональное.
- Якорный коммитмент (`checkbox`) — explicit флаг «готов платить десятки тысяч $/мес». Снимает потребность в эвристиках по тексту коммитмента.
Эти изменения backwards-compatible: старые интервью без новых полей продолжают работать (даты подтянутся из title, интервьюер пустой, якорный = false).
Последнее обновление: 2026-05-08. Документ ведётся в Notion как часть Strategy Hub. Технические детали (как добавить tool, как деплоить, troubleshooting) — в README репозитория.