Notes MCP Server

Отдельный MCP-сервер для сохранения, чтения и списка Markdown-заметок в файловой системе. Он нужен как второй MCP-сервер рядом с внешними источниками данных, например YouTrack MCP:

YouTrack MCP -> агент получает данные -> агент готовит отчет -> Notes MCP сохраняет отчет -> агент отвечает пользователю

Сервер использует Node.js, TypeScript, @modelcontextprotocol/sdk, Streamable HTTP transport и обычные .md файлы. База данных не нужна.

Быстрый запуск

Из корня проекта:

npm install
cp .env.example .env.local
npm run build
npm run start:http

После старта HTTP endpoint доступен по адресу:

http://127.0.0.1:8788/mcp

Healthcheck:

curl http://127.0.0.1:8788/health

Если все в порядке, ответ будет таким:

{"status":"ok","service":"notes-mcp"}

Установка

cd mcp_notes_server
npm install
npm run build

Настройка .env.local

Создай файл mcp_notes_server/.env.local:

MCP_SERVER_TOKEN=change_me
MCP_HTTP_HOST=0.0.0.0
MCP_HTTP_PORT=8788
MCP_HTTP_PATH=/mcp

NOTES_DATA_DIR=./data/notes

Переменные:

• MCP_SERVER_TOKEN - bearer token для HTTP endpoint.
• MCP_HTTP_HOST - host HTTP-сервера.
• MCP_HTTP_PORT - порт HTTP-сервера.
• MCP_HTTP_PATH - путь MCP endpoint.
• NOTES_DATA_DIR - папка для Markdown-файлов.

Запуск HTTP mode

Используй этот режим для bridge, браузерного UI, удаленного подключения или любого клиента, который ходит в MCP по HTTP.

npm run build
npm run start:http

По умолчанию endpoint будет доступен здесь:

http://127.0.0.1:8788/mcp

Healthcheck:

curl http://127.0.0.1:8788/health

MCP-запросы к /mcp должны передавать заголовок:

Authorization: Bearer change_me

Без MCP_SERVER_TOKEN HTTP mode не стартует.

Smoke-проверка HTTP MCP

После запуска можно проверить, что MCP tools реально доступны:

curl -s http://127.0.0.1:8788/mcp \
  -H 'Authorization: Bearer change_me' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

В ответе должны быть tools:

notes_save
notes_read
notes_list

Запуск stdio mode

Для локальных MCP-клиентов, которым нужен stdio transport:

npm run build
npm run start:stdio

В stdio mode HTTP endpoint и bearer token не используются. Клиент запускает процесс сервера сам и общается с ним через stdin/stdout.

Пример команды для MCP-клиента:

{
  "command": "node",
  "args": ["/absolute/path/to/mcp_notes_server/dist/index.js"]
}

Перед подключением stdio mode один раз собери проект через npm run build.

Tools

Сервер регистрирует три tools:

• notes_save - сохраняет Markdown-заметку и возвращает metadata плюс embedded MCP resource с содержимым файла.
• notes_read - читает заметку по id или fileName.
• notes_list - возвращает список последних заметок.

notes_save

Пример аргументов:

{
  "title": "Отчет по задачам авторизации",
  "content": "Markdown content...",
  "tags": ["youtrack", "auth", "report"]
}

Файл сохраняется в NOTES_DATA_DIR с безопасным именем вроде:

2026-06-28-otchet-po-zadacham-avtorizacii.md

Если такой файл уже существует, сервер добавит suffix.

notes_read

{
  "id": "2026-06-28-otchet-po-zadacham-avtorizacii"
}

Или:

{
  "fileName": "2026-06-28-otchet-po-zadacham-avtorizacii.md"
}

notes_list

{
  "limit": 20
}

Формат Markdown

Каждая заметка сохраняется человекочитаемо:

---
title: Отчет по задачам авторизации
createdAt: 2026-06-28T12:00:00.000Z
tags:
  - youtrack
  - auth
  - report
---

# Отчет по задачам авторизации

Markdown content...

Подключение к bridge

Пример MCP_SERVERS_JSON для bridge:

{
  "servers": [
    {
      "id": "notes",
      "name": "Notes",
      "url": "http://127.0.0.1:8788/mcp",
      "authTokenEnv": "NOTES_MCP_TOKEN",
      "enabled": true
    }
  ]
}

В .env.local bridge укажи:

NOTES_MCP_TOKEN=change_me
MCP_SERVERS_JSON={"servers":[{"id":"notes","name":"Notes","url":"http://127.0.0.1:8788/mcp","authTokenEnv":"NOTES_MCP_TOKEN","enabled":true}]}

Если bridge уже подключает YouTrack MCP, добавь Notes вторым элементом массива servers.

Demo prompt

Проверочный prompt для агента:

Найди задачи по авторизации во внешней системе, составь короткий отчет с рисками и сохрани его в заметки. Потом скажи, как называется сохраненная заметка.

Ожидаемый flow:

1. агент вызывает tool из YouTrack MCP;
2. агент анализирует результат;
3. агент вызывает notes_save из Notes MCP;
4. агент отвечает пользователю, что отчет сохранен.

Пользователь при этом не должен знать названия tools.

Безопасность

• HTTP mode требует MCP_SERVER_TOKEN и проверяет Authorization: Bearer <MCP_SERVER_TOKEN>.
• Токены не логируются.
• id и fileName нормализуются и не позволяют path traversal.
• Чтение и запись ограничены NOTES_DATA_DIR.
• Максимальный размер содержимого заметки - 100 KB.