mcplocal

Локальный MCP-сервер для файлов, который позволяет MCP-совместимому клиенту (включая пользовательские MCP-приложения ChatGPT Web, где они доступны) читать, искать и изменять файлы внутри одной явно заданной директории.

Возможности

• Устаревший HTTP+SSE: GET /sse + POST /messages

• Современная MCP HTTP-конечная точка: /mcp

• Проверка работоспособности: /health

• Песочница: каждый путь к файлу разрешается внутри MCP_ROOT

• Необязательная аутентификация Bearer

• Инструменты чтения/поиска для изучения проекта

• Инструменты записи/редактирования для рабочих процессов кодирования

• Удаление отключено по умолчанию

• Нет инструмента для выполнения shell/CLI

• Нет зависимости от внешней базы данных

• Node.js 20+

MCP TypeScript SDK в настоящее время рекомендует Streamable HTTP для удалённых серверов и рассматривает HTTP+SSE как транспорт для обратной совместимости. Этот проект намеренно предоставляет оба варианта, чтобы старые SSE-клиенты могли подключаться, а новые клиенты могли использовать /mcp.

Related MCP server: FilesystemMCP

1. Запуск

cp .env.example .env
# edit MCP_ROOT if needed
npm start

Пример:

MCP_ROOT=~/Projects
MCP_HOST=127.0.0.1
MCP_PORT=8008
MCP_AUTH_TOKEN=change-me

Затем:

SSE:        http://127.0.0.1:8008/sse
Streamable: http://127.0.0.1:8008/mcp
Health:     http://127.0.0.1:8008/health

2. К чему может подключиться ChatGPT Web

ChatGPT Web не может напрямую обращаться к localhost из облачного сервиса. Локальный MCP-сервер должен быть доступен через поддерживаемый механизм Secure MCP Tunnel/частной сети. После того как у вас есть удалённая MCP-конечная точка, добавьте её как пользовательское MCP-приложение в режиме разработчика ChatGPT, просканируйте её инструменты и включите её.

Для туннеля, который отображает локальный сервис, локальный источник:

http://127.0.0.1:8008/sse

или, для современных клиентов:

http://127.0.0.1:8008/mcp

Не открывайте этот сервер для публичного интернета без аутентификации и явной сетевой политики.

3. Инструменты, доступные ChatGPT

• list_files(path, recursive)

• read_file(path, startLine, endLine)

• write_file(path, content, createDirs)

• edit_file(path, oldText, newText, replaceAll)

• search_files(query, path, regex, caseSensitive, maxResults)

• create_directory(path)

• file_info(path)

• delete_file(path) только когда MCP_ENABLE_DELETE=true

Типичный рабочий процесс кодирования:

1. list_files для понимания проекта.

2. search_files для поиска символов.

3. read_file для просмотра соответствующего кода.

4. edit_file для точечного изменения или write_file для нового файла.

5. read_file снова для проверки результата.

4. Модель безопасности

MCP_ROOT — это жёсткая граница. Обход ../ и абсолютные пути за её пределами отклоняются. Двоичные/нечитаемые файлы пропускаются при поиске. Размер файла ограничен MCP_MAX_FILE_BYTES.

Сервер намеренно не предоставляет произвольное выполнение shell. Это означает, что ChatGPT может редактировать код, но не может автоматически запускать rm, curl, менеджеры пакетов, git-команды или произвольные программы через этот MCP.

Для рабочей машины держите MCP_HOST=127.0.0.1 и используйте поддерживаемый Secure MCP Tunnel, а не привязывайте сервер ко всем интерфейсам.

5. Сборка

npm run build
node dist/server.js

Сборка не имеет зависимостей и копирует исполняемый код в dist/.

6. Docker

docker build -t mcplocal .
docker run --rm -p 8008:8008 -v "$PWD:/workspace" mcplocal

7. Примеры запросов в ChatGPT

Inspect this local project and tell me where the authentication flow is implemented. Do not modify anything.

Open src/server.js and refactor the error handling. Before changing it, read the relevant code. Then edit only the necessary section and show me what changed.

Search the project for TODO comments and create a report at reports/todos.md.

Лицензия

MIT