prompt-mcp-server

Переиспользуемый доменно-агностичный MCP-сервер для управления промт-шаблонами и справочными материалами. Подключается к любому проекту в Roo Code (VS Code) без изменения кода сервера.

Сервер не знает про вашу предметную область. Вся специфика — strongSwan, ESP32, схемотехника, что угодно — живёт только в файлах .mcp-prompts/ внутри конкретного проекта. Код сервера одинаков для всех проектов.

---

Как это работает

Roo Code ──stdio (MCP)──▶ prompt-mcp-server ──чтение с диска──▶ <project>/.mcp-prompts/
                                                                ├── prompts/*.md    (промт-шаблоны)
                                                                └── resources/*.{md,yaml}  (справка)

• Транспорт stdio, стандартный MCP-протокол, конфиг — .roo/mcp.json (Roo Code / Cline).
• Без кеша: при каждом prompts/list, prompts/get, resources/list, resources/read сервер заново читает .mcp-prompts/ с диска. Правки .md-файлов подхватываются мгновенно — без перезапуска сервера и без действий в Roo Code.
• Никакой БД и сети — только чтение файлов.
• Подстановка аргументов — Jinja2 со StrictUndefined: незаполненный аргумент даёт явную ошибку, а не тихую пустую строку.
• Невалидный фронтматтер одного файла — файл пропускается (запись в лог), сервер жив.

---

Установка (один раз, глобально)

Сервер ставится глобально и становится доступен как консольная команда prompt-mcp-server для любого количества проектов.

Из репозитория (git)

git clone https://git.shmv.su/majkl/prompt-mcp-server.git
cd prompt-mcp-server

# uv (рекомендуется)
uv tool install .

# или pip
pip install -e .

Обновление до свежей версии после git pull:

git pull
uv tool install . --force

Проверка:

prompt-mcp-server --help

Повторная установка не требуется для новых проектов — они просто указывают на свою папку через --project-dir (см. ниже).

---

Подключение к проекту (Roo Code)

Конфиг кладётся в корень каждого проекта: .roo/mcp.json.

Вариант A — ${workspaceFolder} (основной, переносимый)

{
  "mcpServers": {
    "project-prompts": {
      "command": "prompt-mcp-server",
      "args": ["--project-dir", "${workspaceFolder}"],
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

Проверка подстановки ${workspaceFolder}. Roo Code (как и Cline, от которого он происходит) поддерживает подстановку ${workspaceFolder} в args локального .roo/mcp.json: при загрузке конфига Roo Code заменяет его абсолютным путём открытой рабочей папки. Поэтому файл .roo/mcp.json идентичен во всех проектах и переносим между машинами — именно этот вариант рекомендуется.

Ограничение: подстановка требует открытой рабочей папки. Если открыт только файл без папки (или папка открыта не та), переменная может развернуться в пустое значение — тогда сервер упадёт с понятной ошибкой при старте.

Вариант B — абсолютный путь (fallback)

Используйте, если в вашей версии Roo Code подстановка не срабатывает или вы хотите максимальной предсказуемости:

{
  "mcpServers": {
    "project-prompts": {
      "command": "prompt-mcp-server",
      "args": ["--project-dir", "C:\\path\\to\\project"],
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

На Windows слэши экранируйте (\\) или используйте /. Минус варианта — путь «зашит» в конфиг проекта, и при переносе проекта на другую машину его надо править.

Локальный .roo/mcp.json vs глобальный mcp_settings.json

	Где лежит	Действие
Локальный	<project>/.roo/mcp.json	На проект. Именно этот файл используем для prompt-mcp-server — он переносим вместе с проектом.
Глобальный	~/.config/Roo-Code/mcp_settings.json	Для всех проектов сразу. Годится, но путь к проекту придётся хардкодить или менять вручную при переключении — не наш случай.

---

Структура .mcp-prompts/ внутри проекта

<project>/
├── .roo/mcp.json            ← конфиг MCP (см. выше)
└── .mcp-prompts/
    ├── prompts/             ← промт-шаблоны (YAML-фронтматтер + Jinja2)
    │   ├── code-review.md
    │   └── generate-changelog.md
    └── resources/           ← справочные материалы
        └── code-review-checklist.yaml

Сервер папку не создаёт — только читает. Папки можно коммитить в репозиторий проекта (это часть проекта) или игнорировать в .gitignore — на ваше усмотрение.

Формат промта

---
name: code-review
description: Код-ревью по чеклисту
arguments:
  - name: diff
    description: diff или список изменённых файлов
    required: true
  - name: focus
    description: акцент ревью
    required: false
---
Проведи ревью изменений ниже.

Дифф:

{{ diff }}

{% if focus %}Акцент: {{ focus }}.{% endif %}

• name — идентификатор промта (латиница, цифры, -, _). Если не задан или невалиден, используется имя файла без расширения.
• arguments — необязательно; required: true проверяется до рендера.
• Тело — Jinja2. StrictUndefined: переменная без значения → ошибка (не пустая строка). Поэтому необязательные аргументы в шаблоне оборачивайте явно: {% if focus is defined and focus %} или {{ version | default('Unreleased') }}.

Как добавить новый промт без касания кода сервера

1. Создайте файл prompts/<имя>.md в .mcp-prompts/ проекта.
2. Заполните фронтматтер и текст (см. примеры).
3. Готово. Следующий prompts/list уже покажет новый промт — ничего перезапускать не надо.

---

Как выглядит вызов промта в Roo Code

• В строке ввода Roo Code наберите / — откроется список доступных промтов MCP (их присылает prompts/list), выберите нужный, заполните обязательные аргументы в форме и отправьте. Roo Code подставит отрендеренный текст промта в сообщение.
• Управлять подключением и статусом сервера можно в MCP-панели Roo Code (иконка подключения на панели инструментов) — там же можно перезапустить сервер.

alwaysAllow. При первом обращении к инструменту/промту Roo Code запросит разрешение. Чтобы промты вызывались без подтверждений, добавьте в .roo/mcp.json:

"alwaysAllow": ["prompts/list", "prompts/get", "resources/list", "resources/read"]

Либо оставьте [] и подтверждайте вызовы вручную — сервер всё равно перечитывает файлы с диска на каждый вызов.

---

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

Файлы в resources/ (*.md, *.yaml, *.yml) отдаются как MCP-ресурсы и присоединяются к задаче в Roo Code как контекст. MCP-имя ресурса — имя файла без расширения.

---

Примеры

Полный рабочий пример — в examples/demo-project/: три нейтральных промта (code-review, generate-changelog, summarize-pr) и один ресурс (code-review-checklist). Откройте examples/demo-project как рабочую папку в VS Code — .roo/mcp.json уже на месте.

Проверка вручную (без Roo Code):

# список промтов
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"x","version":"1"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"prompts/list"}' | prompt-mcp-server --project-dir examples/demo-project

---

Командная строка

prompt-mcp-server --project-dir <path> [--log-level INFO]

• --project-dir — папка проекта с .mcp-prompts/. Если не задан — используется переменная окружения PROJECT_PROMPTS_DIR.
• Ни --project-dir, ни PROJECT_PROMPTS_DIR нет — сервер падает с понятным сообщением (не молча отдаёт пустой список).
• Если .mcp-prompts/ в указанной папке не существует — та же политика: ошибка при старте.

---

Разработка

cd prompt-mcp-server
uv sync
uv run python -m prompt_mcp.server --help

Запуск тестов (smoke-тест через MCP-клиент):

uv run python scripts/smoke_test.py --project-dir examples/demo-project