Project Helper MCP Server

Локальный MCP-сервер на Python для безопасного чтения и поиска по файлам текущего проекта. Выбран Python + FastMCP: этот SDK компактно регистрирует инструменты, генерирует JSON Schema из аннотаций и поддерживает stdio.

1. Описание и принципы MCP

VS Code/Copilot Chat запускает MCP-сервер как отдельный процесс по команде из MCP-конфига. Клиент и процесс обмениваются сообщениями JSON-RPC через stdin/stdout (stdio), поэтому сервер не должен писать диагностические сообщения в stdout. В этом проекте такие сообщения направляются в logs/mcp-server.log и stderr.

MCP tool здесь — именованный инструмент с описанием, JSON Schema входных параметров и структурированным результатом. Агент выбирает инструмент по описанию, передаёт валидированные параметры, а сервер возвращает объект контракта {status, data, error}.

Related MCP server: Context MCP

2. Установка и запуск на macOS

cd "path/to/project"
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
cp .env.example .env

В .env укажите путь к проекту, который разрешено читать:

PROJECT_ROOT=/absolute/path/to/project

Для ручной проверки запуска:

PROJECT_ROOT="$PWD" .venv/bin/python server.py

Процесс будет ждать MCP-сообщения в stdin. Не добавляйте print() в сервер: stdout зарезервирован для протокола.

3. Инструменты

FastMCP публикует схемы параметров на основе типов и ограничений Field.

Пути в file_glob фильтруются относительно корня проекта. query для search_in_files — регулярное выражение; некорректный regex возвращается как ошибка инструмента.

4. Tool outputs contract

Каждый успешно выполненный вызов возвращает:

{
	"status": "success",
	"data": { "...": "tool-specific JSON data" },
	"error": null
}

Ошибка операции возвращается без выполнения опасного действия:

{
	"status": "error",
	"data": null,
	"error": { "code": "path_outside_project", "message": "..." }
}

data всегда содержит структурированный объект/массив, а error равен null при успехе. Ошибки валидации схемы до вызова функции обрабатывает MCP SDK.

5. Ограничения безопасности

• Разрешён только корень из PROJECT_ROOT (или текущая директория, если переменная не задана).

• Каждый путь нормализуется через Path.resolve() и проверяется через relative_to(root).

• Абсолютные пути вне корня, ..-переходы и симлинки, уводящие наружу, отклоняются.

• Сервер только читает файлы и не выполняет код, не удаляет и не изменяет файлы.

• Секреты не хранятся в коде; .env и логи исключены из git. Не помещайте ключи в параметры tool-запросов.

• Бинарные и нечитаемые UTF-8 файлы пропускаются поиском.

6. Как подключить к VS Code / GitHub Copilot Chat

1. Установите зависимости из раздела выше и убедитесь, что существует .venv/bin/python.

2. Откройте .vscode/mcp.json. В ${workspaceFolder} будет подставлен открытый корень проекта.

3. При необходимости измените PROJECT_ROOT в конфиге на каталог, который сервер должен читать. Для текущего репозитория оставьте ${workspaceFolder}.

4. Откройте Command Palette и выполните Developer: Reload Window, затем откройте Copilot Chat.

5. В MCP/Tools-индикаторе чата проверьте сервер project-helper; подробные вызовы смотрите в logs/mcp-server.log, а ошибки запуска — в View > Output, канал GitHub Copilot Chat/MCP (название канала может зависеть от версии VS Code).

Конфигурация использует актуальную для VS Code форму .vscode/mcp.json:

{
	"servers": {
		"project-helper": {
			"type": "stdio",
			"command": "${workspaceFolder}/.venv/bin/python",
			"args": ["${workspaceFolder}/server.py"],
			"env": {
				"PROJECT_ROOT": "${workspaceFolder}"
			}
		}
	}
}

7. Таблица проверочных запросов

Первые три запроса должны привести к реальному вызову MCP tool. После ручной проверки замените logs/verification-*.txt на фактические фрагменты логов или скриншоты.

Для каждого реального вызова скопируйте из logs/mcp-server.log строку tool_call и следующую строку tool_result в соответствующий файл подтверждения. Не сохраняйте в подтверждения секреты.

Для запроса №2 подтверждение уже добавлено: на скриншоте видны tool list_project_files, параметр extension: ".py", результат с единственным файлом server.py, а в Output — успешные события tool_call и tool_result.

Для запросов №1 и №3 подтверждение добавлено по новым скриншотам и записям в mcp-server.log: оба вызова завершились со статусом success.

8. Ссылки на код

Номера строк актуальны для текущей версии файлов и обновляются при изменениях.

• Поднятие stdio-сервера и регистрация инструментов: server.py.

• Общая проверка пути и контракт ответа: server.py.

• Общее логирование вызовов и ошибок: server.py.

• Реализация search_in_files: server.py; место логирования: server.py; пример лога: logs/mcp-server.log (создаётся после первого вызова).

• Реализация list_project_files: server.py; место логирования: server.py.

• Реализация read_file_snippet: server.py; место логирования: server.py.

• Реализация find_symbol_usages: server.py; место логирования: server.py.

• Пример запроса для read_file_snippet находится в таблице выше; подтверждение хранится в logs/verification-03-read.txt после ручного запуска.

Пример фактического лога после запроса поиска:

INFO tool_call name=search_in_files params={"query": "PROJECT_ROOT", "file_glob": "*.py", "max_results": 5}
INFO tool_result name=search_in_files status=success