# MCP Notes Server

MCP-сервер для работы с заметками. Предоставляет AI-клиентам набор инструментов для создания, чтения и поиска заметок. Работает по стандартному протоколу MCP, поэтому подходит для любого MCP-совместимого клиента.

## Что такое MCP?

MCP (Model Context Protocol) — открытый протокол, который позволяет AI-моделям безопасно подключаться к внешним инструментам и данным. Сервер предоставляет набор инструментов (tools), которые модель может вызывать по мере необходимости. FastMCP — Python-фреймворк для реализации таких серверов.

## Зачем этот сервер?

Сервер даёт AI-клиенту простой способ управлять заметками: создавать, просматривать и искать по тексту. Все данные хранятся в локальном JSON-файле — никаких внешних сервисов и API-ключей не требуется.

## Установка

### 1. Клонируйте репозиторий
```bash
git clone <repo-url>
cd mcp-notes-server
```

### 2. Создайте виртуальное окружение
```bash
python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate  # Windows
```

### 3. Установите зависимости
```bash
pip install -r requirements.txt
```

## Запуск сервера
```bash
python -m src.server
```

## Как проверить, что всё работает

Есть два независимых способа. Оба — просто на Python.

### Способ 1: быстрый тест логики (рекомендуется начать с него)

```bash
python test_client.py
```
Этот скрипт напрямую вызывает функции хранилища — проверяет создание, чтение и поиск заметок. Если видите сообщение "Все тесты пройдены" — база работает.

### Способ 2: полноценный MCP-клиент

```bash
python example_client.py
```
Этот скрипт запускает сам MCP-сервер как подпроцесс и общается с ним по протоколу MCP через stdio. В выводе вы увидите:

- список доступных инструментов, полученный по протоколу;
- результат вызова create_note;
- результат вызова list_notes;
- результат вызова search_notes.

Это и есть демонстрация того, что сервер работает как настоящий MCP-сервер.

## Запуск сервера вручную

```bash
python -m src.server
```

Сервер запустится и будет ждать JSON-RPC сообщений на stdin. Это стандартный транспорт MCP. Обычно сервер запускает сам клиент, поэтому вручную его запускать нужно только для отладки.

## Подключение к реальным клиентам

### MCP Inspector (нужен Node.js)

Это официальный отладочный инструмент с веб-интерфейсом. Требует установленный Node.js.

```bash
npx @modelcontextprotocol/inspector python -m src.server
```
Откроется браузер с панелью, где можно вызывать инструменты вручную.

### можно к Claude Desktop (если доступен)

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

Сервер предоставляет три инструмента.

### `create_note`

Создаёт новую заметку с авто-ID и timestamp.

- Параметры: `text: str` — текст заметки
- Возвращает: `str` — подтверждение с ID созданной заметки
- Пример вызова: `create_note(text="Купить молоко")`
- Пример ответа: `Заметка создана. ID: 4, текст: Купить молоко`

### `list_notes`

Возвращает список всех заметок.

- Параметры: нет
- Возвращает: `list[dict]` — список заметок, каждая с полями `id`, `text`, `created_at`
- Пример вызова: `list_notes()`
- Пример ответа: `[{"id": 1, "text": "...", "created_at": "..."}, ...]`

### `search_notes`

Ищет заметки по подстроке в тексте (без учёта регистра).

- Параметры: `query: str` — поисковый запрос
- Возвращает: `list[dict]` — список найденных заметок
- Пример вызова: `search_notes(query="хлеб")`
- Пример ответа: `[{"id": 3, "text": "Купить хлеб...", "created_at": "..."}]`

## Пример вывода example_client.py

```bash
Тест 2: MCP-протокол (полноценный клиент)

Сессия инициализирована.

Доступные инструменты:
  - create_note: Создаёт новую заметку с указанным текстом.
  - list_notes: Возвращает список всех заметок.
  - search_notes: Ищет заметки по подстроке в тексте (без учёта регистра).

--- create_note ---
Заметка создана. ID: 4, текст: Заметка, созданная через MCP-протокол

--- list_notes ---
[
  {"id": 1, "text": "Купить хлеб", "created_at": "..."},
  ...
]

--- search_notes(query='Python') ---
[
  {"id": 3, "text": "Изучить декораторы в Python", "created_at": "..."}
]

MCP-клиент успешно отработал.
```

## Структура проекта

```bash
mcp-notes-server/
├── src/
│   ├── __init__.py
│   ├── storage.py
│   └── server.py
├── notes.json
├── test_client.py
├── example_client.py
├── .gitignore
├── README.md
└── requirements.txt
```