cosense-mcp-worker

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

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

Использование из различных MCP-инструментов

• Имя: Cosense

• MCP-эндпоинт: https://<worker-host>/mcp

• Аутентификация: OAuth

Related MCP server: Remote MCP Server with Bearer Auth

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

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

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

Предоставляемые эндпоинты

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 check запускает линтер, проверку типов, модульные тесты, синхронизацию типов Worker binding и проверку бандла перед развёртыванием.

pnpm check
pnpm wrangler dev --local

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

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

pnpm run deploy

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

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

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

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

4. Убедитесь, что Team Domain в Zero Trust совпадает с CF_ACCESS_TEAM_DOMAIN.

5. В Advanced settings приложения включите Managed OAuth.

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

Authorization Code Flow, PKCE, вход, refresh-токены, OAuth discovery и Access Policy полностью обрабатываются Cloudflare Access. Сам Worker не реализует OAuth-сервер.

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

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

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

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

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

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

• Origin для /mcp разрешён полностью. Приоритет отдаётся совместимости с 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ヘルプ

Проект вдохновлён yosider/cosense-mcp-server. Данный проект не копирует код этого репозитория, а является новой реализацией для Cloudflare Workers.