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

Обзор

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

Related MCP server: ONOS MCP Server

Функции

• Динамическая генерация инструментов: инструменты 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 ( urls.json ): Убедитесь, что файл 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 : Ваш файл .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:

docker build -t ise-mcp:latest .

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

docker build -t ise-mcp:latest -f src/Dockerfile .

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

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

{
  "mcpServers": {
    // ... other servers ...
    "ISE_MCP": {
      "command": "docker",
      "args": [
        "run",
        "-i",         // Essential for STDIO interaction
        "--rm",       // Automatically remove the container when it exits
        "--env-file=/Users/username/mcp_servers/ISE_MCP/.env", // Mounts your .env file
        "ise-mcp:latest" // The image we just built
      ],
      "cwd": "/Users/username/mcp_servers/ISE_MCP" // Ensures paths are correct
    }
    // ... other servers ...
  }
}

Объяснение аргументов 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 .

docker-compose up --build

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

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

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

Предпосылки

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

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

Исполнение

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

python src/ise_mcp_server/server.py

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

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

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

python -m fastmcp dev src/ise_mcp_server/server.py --with httpx --with pydantic --with python-dotenv

После выполнения этой команды запустится 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 --directory /Users/username/mcp_servers/ISE_MCP run fastmcp run src/ise_mcp_server/server.py --transport stdio

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

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

{
  "mcpServers": {
    // ... other servers ...
    "ISE_LOCAL_UV": { // Using a different key to distinguish
      "command": "uv",
      "args": [
        "--directory",
        "/Users/username/mcp_servers/ISE_MCP",
        "run",
        "fastmcp",
        "run",
        "src/ise_mcp_server/server.py",
        "--transport",
        "stdio"
      ],
      "cwd": "/Users/username/mcp_servers/ISE_MCP", // Ensures .env is found if relative paths are used by fastmcp for .env loading
      "transportType": "stdio" // Explicitly tell Claude this is an STDIO server
    }
    // ... other servers ...
  }
}

Эта конфигурация будет принята 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 ).

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

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

// Example arguments for a tool call (client-dependent format)
{
  "params": {
    "filter_expression": "name.CONTAINS.mydevice",
    "query_params": {
      "size": 10,
      "page": 1
    }
  }
}

• 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