Сервер ISE MCP (использующий FastMCP)

Обзор

Сервер ISE MCP — это сервер Model Context Protocol (MCP), созданный с использованием библиотеки Python fastmcp . Он динамически представляет конечные точки API Cisco Identity Services Engine (ISE) как структурированные, обнаруживаемые инструменты MCP. Этот сервер позволяет клиентам взаимодействовать с API Cisco ISE REST стандартизированным способом, предлагая такие функции, как динамическая генерация инструментов и фильтрация ответов API.

Функции

• Динамическая генерация инструментов: инструменты MCP автоматически создаются на основе записей в файле конфигурации src/ise_mcp_server/urls.json .

• Интеграция FastMCP: использует библиотеку fastmcp для надежной реализации сервера MCP, включая генерацию схем и обработку запросов.

• Асинхронные вызовы API: использует httpx.AsyncClient для неблокируемой связи с Cisco ISE.

• Фильтрация API: поддерживает фильтрацию результатов API Cisco ISE с помощью аргументов filter_expression и query_params в каждом инструменте.

• Конфигурация на основе среды: сведения о подключении Cisco ISE (базовый URL, имя пользователя, пароль) и параметры проверки SSL ( ISE_VERIFY_SSL ) настраиваются с помощью файла .env .

• Подробные строки документации: динамически генерируемые инструменты включают в себя подробные строки документации, объясняющие их назначение, конечную точку API ISE, на которую они нацелены, и порядок использования параметров фильтрации.

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

• Потоковый HTTP-транспорт: настроен на использование streamable-http транспорта по умолчанию для веб-доступа.

Настраивать

Сервер

{ "mcpServers": { "ise": { "command": "python", "args": [ "ise_mcp_server.py", "--oneshot" ], "env": { "ISE_BASE": " https://devnetsandboxise.cisco.com ", "USERNAME": "readonly", "PASSWORD": "ISEisC00L" } } } }

Требования

• Python 3.9 или выше.

• Необходимые пакеты Python перечислены в requirements.txt (в корне проекта). Установите их с помощью:

  pip install -r requirements.txt

  Или, если использовать uv :

  uv pip install -r requirements.txt

  Ключевые зависимости включают fastmcp , httpx , pydantic и python-dotenv . (Убедитесь, что requirements.txt отражает httpx вместо requests ).

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

1. Переменные среды: создайте файл .env в корневом каталоге проекта ( /Users/username/mcp_servers/ISE_MCP/.env ) с вашими учетными данными API Cisco ISE и базовым URL-адресом:

   ISE_BASE="https://your-ise-instance.example.com" USERNAME="your-ise-api-username" PASSWORD="your-ise-api-password" # Optional: Controls SSL certificate verification for ISE API calls. # Default is true. Set to "false" to disable (insecure). # Or provide a path to a CA bundle file, e.g., "/path/to/your/ca.pem". ISE_VERIFY_SSL="true"

2. Конфигурация URL ( Убедитесь, что файл src/ise_mcp_server/urls.json (расположенный в том же каталоге, что и src/ise_mcp_server/server.py ) присутствует и структурирован правильно. Этот файл определяет конечные точки API ISE, которые будут представлены как инструменты MCP.

   [ { "URL": "/ers/config/endpoint", "Name": "Endpoints", "FilterableFields": ["mac", "name", "description", "identityGroupName"] }, { "URL": "/ers/config/identitygroup", "Name": "Identity Groups", "FilterableFields": ["name", "description"] } // ... more endpoints ]

   • URL : Относительный путь к конечной точке API Cisco ISE.

   • Name : понятное человеку имя, используемое для получения имени инструмента MCP (например, «Endpoints» становится endpoints инструмента).

   • FilterableFields : Массив строк, перечисляющих известные поля, которые можно использовать с filter_expression для этой конечной точки. Этот список поддерживается пользователем и имеет решающее значение для эффективной фильтрации.

Запуск сервера с Docker для Claude Desktop

Этот сервер предназначен для работы в качестве контейнера Docker, особенно при использовании с такими клиентами, как Claude Desktop, которые взаимодействуют через STDIO.

Предпосылки

1. Docker установлен: убедитесь, что Docker Desktop установлен и запущен.

2. Файл Ваш файл .env (как описано в разделе «Конфигурация») должен находиться в корне проекта ( /Users/username/mcp_servers/ISE_MCP/.env ).

3. Dockerfile настроен для STDIO: Dockerfile в этом проекте ( Dockerfile ) должен быть настроен на использование транспорта stdio . ENTRYPOINT должен выглядеть так:

   ENTRYPOINT ["python", "-m", "ise_mcp_server", "--transport", "stdio"]

   Убедитесь, что файл .envне копируется.

Создайте образ Docker

Перейдите в каталог, содержащий Dockerfile ( /Users/username/mcp_servers/ISE_MCP/ ), и создайте образ Docker:

Альтернативный вариант, если сборка выполняется из корня проекта:

Настроить рабочий стол Клода

Обновите конфигурацию сервера Claude Desktop MCP ( claude_desktop_config.json или cline_mcp_settings.json ) для сервера «ISE_MCP» следующим образом:

Объяснение аргументов Docker:

• run : запускает контейнер Docker.

• -i : (Интерактивно) Сохраняет STDIN открытым, даже если он не подключен, что имеет решающее значение для связи MCP на основе STDIO.

• --rm : Автоматически удаляет контейнер при выходе.

• --env-file : Указывает путь к файлу .env на хост-машине. Docker загрузит эти переменные в контейнер.

• ise-mcp:latest : Имя и тег образа Docker для запуска.

• cwd : Устанавливает рабочий каталог для команды, гарантируя, что относительные пути (например, для --env-file ) будут разрешены правильно, если Claude Desktop запускает команды из другого каталога по умолчанию.

Запуск с Docker Compose (альтернатива для локального тестирования)

Файл docker-compose.yml также предоставляется для локального тестирования. Он создает образ и запускает контейнер, загружая переменные среды из файла .env .

Этот метод подходит для прямого тестирования, но для интеграции Claude Desktop предпочтительнее использовать приведенную выше конфигурацию docker run .

Запуск сервера локально (без Docker)

Для разработки или когда Docker нежелателен, вы можете запустить сервер напрямую с помощью Python.

Предпосылки

1. Среда Python: убедитесь, что у вас установлен Python 3.9+ и установлены зависимости из requirements.txt .

2. Файл Файл .env должен присутствовать в корне проекта ( /Users/username/mcp_servers/ISE_MCP/.env ).

Исполнение

Перейдите в корневой каталог проекта и запустите:

По умолчанию src/ise_mcp_server/server.py настроен на запуск сервера с использованием streamable-http транспорта, обычно доступного по адресу http://127.0.0.1:8000/mcp . Вы можете изменить server.py , чтобы изменить транспорт (например, на stdio ) или другие параметры сервера, если это необходимо для вашего конкретного клиента.

Разработка и тестирование с помощью MCP Inspector (локальный Python)

Для локального развития с MCP Inspector:

После выполнения этой команды запустится MCP Inspector.

• Для тестирования STDIO с помощью Inspector:

  1. Выберите «STDIO» в качестве типа транспорта в Инспекторе.

  2. Задайте команду для запуска сервера как python src/ise_mcp_server/server.py .

  3. Подключитесь к серверу.

• Для HTTP-тестирования с помощью Inspector:

  1. Запустите python src/ise_mcp_server/server.py в отдельном терминале, чтобы запустить сервер (по умолчанию он будет использовать streamable-http ).

  2. В MCP Inspector выберите «HTTP».

  3. Установите URL-адрес на http://127.0.0.1:8000/mcp (или настроенную вами конечную точку).

  4. Подключитесь к серверу.

Запуск локально с помощью uv и fastmcp run (альтернатива STDIO)

Если у вас uv и fastmcp установлены глобально или в вашей среде, вы также можете запустить сервер с помощью команды fastmcp run , которая часто бывает полезна для клиентов на основе STDIO.

Предварительные условия:

1. uv установлен и находится в вашей переменной PATH.

2. fastmcp установлен в среде, которую будет использовать uv (или глобально).

3. Файл .env присутствует в корне проекта.

Исполнение:

Эта команда сообщает uv выполнить fastmcp run src/ise_mcp_server/server.py --transport stdio в указанном каталоге проекта. Флаг --transport stdio важен для клиентов, ожидающих STDIO.

Конфигурация Claude Desktop для метода Если вы предпочитаете этот метод для Claude Desktop, вы можете настроить его следующим образом:

Эта конфигурация будет принята Claude Desktop, если вы назовете свой сервер "ISE_LOCAL_UV" или соответствующим образом измените ключ. Обратите внимание, что fastmcp run автоматически загрузит файл .env из текущего рабочего каталога (в данном случае /Users/username/mcp_servers/ISE_MCP ).

Взаимодействие с сервером

После запуска к серверу ISE MCP можно получить доступ с помощью любого MCP-совместимого клиента (например, MCP Inspector).

Инструмент обнаружения

Клиенты могут обнаружить доступные инструменты. Каждый инструмент соответствует записи в urls.json . Названия инструментов выводятся из поля Name (например, "Identity Groups" становится identity_groups ).

Вызов инструмента

Инструменты вызываются с одним необязательным аргументом params , который является экземпляром модели Pydantic ( FilterableToolInput или NonFilterableToolInput ).

Пример: Вызов инструмента Клиент MCP обычно разрешает вызывать инструмент без явных аргументов, если входная модель инструмента использует default_factory .

Пример: Вызов инструмента Аргументы будут структурированы в соответствии с моделью Pydantic. Для инструмента, созданного из конечной точки с FilterableFields :

• filter_expression (string, необязательно): Задает фильтры в формате fieldName.OPERATION.value (например, mac.EQUALS.AA:BB:CC:DD:EE:FF ). Обратитесь к docstring инструмента для доступных FilterableFields и поддерживаемых операций ISE (например, CONTAINS, EQUALS, STARTSWITH).

• query_params (dict, необязательно): Позволяет указывать другие произвольные параметры запроса (например, {"size": 100, "page": 2} ). Они передаются напрямую в API ISE.

Если конечная точка в urls.json имеет пустой массив FilterableFields , соответствующий инструмент будет принимать только query_params .

Подробную информацию о конечной точке и доступных фильтруемых полях см. в динамически сгенерированной строке документации каждого инструмента.

Ведение журнала

Сервер использует стандартный модуль logging Python, настроенный fastmcp . Сообщения журнала, связанные с операциями сервера и взаимодействиями API, будут выводиться на консоль.

Лицензия

Лицензия Apache 2.0