cosense-mcp-worker

Это stateless-сервер Remote MCP для управления одним проектом Cosense (ранее Scrapbox). Работает на Cloudflare Workers, для HTTP-маршрутизации используется Hono, для MCP — createMcpHandler() из Cloudflare Agents и MCP SDK v2. Реализация OAuth не встроена в Worker — она делегируется Cloudflare Access Managed OAuth.

Один Worker привязан к одному проекту Cosense и одному connect.sid. Из аргументов инструментов MCP нельзя изменить или указать другой проект или учётные данные.

Развёртывание одним кликом в Cloudflare

С помощью этой кнопки вы можете создать, собрать и развернуть Worker в своей собственной учётной записи Cloudflare. На экране настройки введите имя Worker, а также COSENSE_PROJECT_NAME, CF_ACCESS_TEAM_DOMAIN, CF_ACCESS_AUD и секрет COSENSE_SID.

Создание приложения Cloudflare Access, включение Managed OAuth и настройка политик Access выполняются самим пользователем уже после развёртывания.

Предоставляемые конечные точки

Инструменты MCP

Локальная настройка

Необходимы: Node.js 20 или новее, Corepack, учётная запись Cloudflare с доступом к Cloudflare Zero Trust и идентификатор сессии с правами на целевой проект Cosense.

git clone <リポジトリURL> cosense-mcp-worker
cd cosense-mcp-worker
corepack enable
pnpm install

Значения, не являющиеся секретами, задаются в wrangler.jsonc.

"vars": {
  "COSENSE_PROJECT_NAME": "your-project",
  "CF_ACCESS_TEAM_DOMAIN": "https://your-team.cloudflareaccess.com",
  "CF_ACCESS_AUD": "YOUR_ACCESS_APPLICATION_AUDIENCE_TAG"
}

Идентификатор сессии обязательно задавайте как Worker Secret. Не сохраняйте его в wrangler.jsonc, в исходном коде или в Git.

pnpm wrangler secret put COSENSE_SID

Для локальной разработки используйте файл .dev.vars, который не коммитится в репозиторий.

COSENSE_SID=your-connect.sid-value

Проверка и локальный запуск выполняются следующим образом.

pnpm lint
pnpm typecheck
pnpm test
pnpm wrangler dev --local

Настройка Cloudflare Access Managed OAuth

Выполняйте следующие команды только после того, как будете готовы к развёртыванию.

pnpm deploy

Затем в панели управления Cloudflare Zero Trust создайте приложение Access для домена Worker.

1. Создайте приложение MCP server для домена и пути /mcp Worker.

2. Настройте политику Access, разрешающую использование целевого проекта Cosense для нужных пользователей или групп.

3. Скопируйте тег Application Audience (AUD) и задайте его в CF_ACCESS_AUD.

4. Убедитесь, что Team Domain совпадает со значением CF_ACCESS_TEAM_DOMAIN.

5. В расширенных настройках приложения включите Managed OAuth.

6. Зарегистрируйте https://<worker-host>/mcp в MCP-клиенте.

Authorization Code Flow, PKCE, вход в систему, обновление токенов, OAuth discovery и политики Access — всё это обеспечивает Cloudflare Access. Сам Worker не реализует OAuth-сервер.

Worker принимает Cf-Access-Jwt-Assertion и передаёт запросы к /mcp в обработчик MCP только после проверки подписи RS256, issuer и AUD с использованием JWKS-эндпоинта Team.

Информация об OAuth discovery при использовании Managed OAuth возвращается клиенту слоем Access. Внутри Worker не добавляются OAuth-эндпоинты и не создаётся собственный сервер авторизации.

Свойства безопасности

• COSENSE_SID обрабатывается как Secret binding и никогда не включается в JSON-ответы или логи.

• Запросы к /mcp без assertion Access или с недействительным assertion отклоняются с кодом 401.

• Подпись Access JWT проверяется с помощью https://<team-domain>/cdn-cgi/access/certs, а также проверяются issuer и AUD.

• Для /mcp разрешены все источники (Origin). Приоритет отдаётся совместимости с Remote MCP-клиентами, а контроль доступа обеспечивается через OAuth-токены Cloudflare Access и проверку JWT в Worker.

• Входные данные инструментов MCP, отсутствующие в схеме, отклоняются, поэтому вызывающая сторона не может перезаписать проект или учётные данные.

• Произвольные ошибки со стороны Cosense не передаются как есть — они ограничиваются ошибками на уровне отдельных операций.

• Чтобы случайно не возвращать огромные ответы, вывод инструментов ограничен 100 000 символами.

Структура каталогов

src/
  config.ts                 Worker bindingの検証
  index.ts                  Honoルートとstateless MCP HTTP transport
  middleware/access-auth.ts Access JWTの検証
  mcp/server.ts             MCP SDK v2 server factory
  mcp/tools/                ツールごとのスキーマと登録処理
  cosense/client.ts         Cosense adapter
  cosense/formatter.ts      LLM向けページ整形
  cosense/insert-lines.ts   純粋な挿入位置計算
test/                       外部Cosense APIを呼ばないユニットテスト

Справочные материалы

• Cloudflare Agents MCP handler APIs

• Cloudflare Access Managed OAuth

• Cloudflare Access JWT validation

• Cosense API help

Идея основана на yosider/cosense-mcp-server. Данный проект не копирует код указанного репозитория, а представляет собой новую реализацию, предназначенную для Cloudflare Workers.