Универсальный фреймворк инструментов MCP

Многоразовая основа на Python для инструментов Model Context Protocol. Фреймворк централизует регистрацию, обнаружение, разрешения, разделение режимов операций, структурированные ошибки, журналирование, конфигурацию, вывод состояния/статуса и соглашения о расширениях.

Границы проектирования

Фреймворк — это основа MCP-сервера, а не универсальная оболочка, контроллер файловой системы или механизм политик. Инструменты регистрируются явно и выполняются через одну границу разрешений.

Инструмент должен пройти обе проверки: его режим операции включён, и требуемые области присутствуют в контексте выполнения.

Related MCP server: achmadya-dev/mcp-core

Включённая поверхность

Требования

• Python 3.10+

• Официальный MCP Python SDK, закреплённый на mcp==2.0.0

Быстрый старт

python -m venv .venv
. .venv/bin/activate
pip install -e .
python -m unittest discover -s tests -p "test_*.py"

Запустите сервер через MCP SDK:

mcp run server.py

Для интерактивной разработки с MCP Inspector:

mcp dev server.py

Конфигурация

Копируйте и изменяйте пример только тогда, когда требуются операции, отличные от чтения.

{
  "server_name": "Universal MCP Tool Framework",
  "enabled_modes": ["read"],
  "log_level": "INFO"
}

read — единственный режим по умолчанию. Чтобы разрешить зарегистрированный инструмент записи, добавьте write; чтобы разрешить зарегистрированный инструмент выполнения, добавьте execute. Включение режима не обходит требуемые области для каждого инструмента.

Запустите сервер с выбранным файлом конфигурации:

UNIVERSAL_MCP_CONFIG=config.json mcp run server.py

Добавление инструмента

1. Выберите один режим операции.

2. Объявите все требуемые области.

3. Зарегистрируйте обработчик через ToolRegistry.

4. Добавьте тест для обнаружения, разрешённого выполнения и путей отклонения.

5. Предоставьте тонкий MCP-обработчик только в том случае, если инструмент принадлежит публичной поверхности сервера.

from universal_mcp.models import OperationMode
from universal_mcp.registry import ToolRegistry

registry = ToolRegistry()

@registry.register(
    name="inventory_get_item",
    description="Return one inventory item by stable identifier.",
    mode=OperationMode.READ,
    required_scopes={"inventory:read"},
)
def inventory_get_item(item_id: str) -> dict[str, str]:
    return {"item_id": item_id}

Вызывайте его через ToolRuntime.execute(), чтобы общий контракт разрешений, журналирования и ошибок всегда применялся.

Контракт результата

Все выполнения во время выполнения создают этот стабильный конверт:

{
  "ok": true,
  "data": {},
  "error": null
}

Отклонённые и неудачные запросы используют ok: false и машиночитаемый код ошибки, такой как tool_not_found, permission_denied или tool_execution_failed.

Структура репозитория

.
├── config.example.json
├── pyproject.toml
├── server.py
├── src/universal_mcp/
│   ├── config.py
│   ├── examples.py
│   ├── models.py
│   ├── registry.py
│   ├── runtime.py
│   └── server.py
└── tests/test_framework.py

Проверка

python -m unittest discover -s tests -p "test_*.py"

Тестовый набор проверяет обнаружение, доступ на чтение по умолчанию, запрет записи/выполнения по умолчанию, соблюдение областей, структурированные ошибки, вывод статуса и JSON-конфигурацию.

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

Репозиторий также предоставляет umcp-scaffold — управляемый генератор для повторяемых стартов Python-проектов.

Создайте полностью инициализированный проект. По умолчанию генератор создаёт локальный Git-репозиторий, создаёт изолированный .venv, устанавливает локальные зависимости и проверяет сгенерированный проект.

umcp-scaffold create "My Project" ./my-project --type mcp-tool

Проверьте сгенерированный проект позже:

umcp-scaffold validate ./my-project

Каждый сгенерированный проект получает .project-state.json с версией схемы, именем, именем пакета, типом шаблона, состоянием жизненного цикла, флагами Git/зависимостей, временем создания и последним состоянием проверки. Генератор отклоняет непустые целевые каталоги, а не перезаписывает проект.

Локальный набор инструментов для анализа и тестирования кода

umcp-quality проверяет локальный Python-проект и возвращает машиночитаемый отчёт о качестве с результатами PASS, FAIL и WARNING.

umcp-quality ./my-project
umcp-quality ./my-project --format markdown

FAIL приводит к ненулевому статусу выхода команды. WARNING указывает на неполное, но не ошибочное состояние, например, отсутствие виртуальной среды, тестов, каталога конфигурации или недоступную историю Git.