# Notes MCP Server

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

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

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

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

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

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

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

```text
http://127.0.0.1:8788/mcp
```

Healthcheck:

```bash
curl http://127.0.0.1:8788/health
```

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

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

## Установка

```bash
cd mcp_notes_server
npm install
npm run build
```

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

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

```env
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.

```bash
npm run build
npm run start:http
```

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

```text
http://127.0.0.1:8788/mcp
```

Healthcheck:

```bash
curl http://127.0.0.1:8788/health
```

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

```text
Authorization: Bearer change_me
```

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

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

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

```bash
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:

```text
notes_save
notes_read
notes_list
```

## Запуск stdio mode

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

```bash
npm run build
npm run start:stdio
```

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

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

```json
{
  "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`

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

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

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

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

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

### `notes_read`

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

Или:

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

### `notes_list`

```json
{
  "limit": 20
}
```

## Формат Markdown

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

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

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

Markdown content...
```

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

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

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

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

```env
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 для агента:

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

Ожидаемый flow:

```text
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.