- Регистрация
- 23 Август 2023
- Сообщения
- 3 641
- Лучшие ответы
- 0
- Реакции
- 0
- Баллы
- 243
Offline
MCPHero - новая библиотека/проект для Python для использования MCP tools как native tools в ИИ библиотеках типа openai, которые не поддерживают MCP сами по себе.
# В openai нельзя вызвать completions с MCP сервераами
response = client.chat.completions.create(
model="gpt-4o",
messages=messages,
tools=tools, # tools - должны быть специальные dict'ы, не ссылки до MCP
# mcp_tools=my_mcs_tools # такого аргумента, к сожалению, нет
# mcp_servers=my_mcp_servers # такого аргумента, к сожалению, тоже нет
tool_choice="auto"
)
Из-за этого возникает нужда либо переписать все на agentic библотеки(pydantic_ai, langchain, agents и тп), которые поддерживают MCP сервера, либо же писать свои адаптеры, которые пройдутся по lifecycle MCP, а потом замепят это все в формат openai:
Initialize -> Authorize -> List MCP Tools -> map_MCP_tool_to_openai_tool() -> openai_call
Поддерживать такое не хочется, особенно учитывая, что потом надо делать обратный меппинг:
openai_response.tool_calls -> map_openai_tool_call_to_MCP_payload -> Call MCP Tool
Поддерживать такое желания нет, каких-либо решений в открытом доступе найдено не было.
Что MCPHero за библиотека?
У MCPHero одна задача - конвертировать и поддерживать mapping MCP в нативные ИИ либы и обратно, чтобы можно было использовать MCP как tools. Пример:
import asyncio
from openai import OpenAI
from mcphero import MCPToolAdapterOpenAI
async def main():
adapter = MCPToolAdapterOpenAI("https://api.mcphero.app/mcp/your-server-id")
# Здесь мы получаем тулы из MCP сервера, но сразу в формате openai
tools = await adapter.get_tool_definitions()
messages = [{"role": "user", "content": "What's the weather in London?"}]
response = client.chat.completions.create(
model="gpt-4o",
messages=messages,
tools=tools, # openai не знает, что это MCP tools, он вызывает "свои"
)
if response.choices[0].message.tool_calls:
tool_results = await adapter.process_tool_calls(
response.choices[0].message.tool_calls
) # тут MCPHero обрабатывает openai tool_calls,
# вызывая MCP сервер по HTTP по его tools
messages.append(response.choices[0].message)
messages.extend(tool_results) # результаты тоже openai формата
final_response = client.chat.completions.create(
model="gpt-4o",
messages=messages,
tools=tools,
)
print(final_response.choices[0].message.content)
asyncio.run(main())
Также есть поддержка другой "немспшной" либы - google-genai (gemini)
import asyncio
from google import genai
from google.genai import types
from mcphero import MCPToolAdapterGemini
async def main():
adapter = MCPToolAdapterGemini("https://api.mcphero.app/mcp/your-server-id")
client = genai.Client(api_key="your-api-key")
# Один тул(можно и get_tool_definitions())
tool = await adapter.get_tool()
response = client.models.generate_content(
model="gemini-2.5-flash",
contents="What's the weather in London?",
config=types.GenerateContentConfig(
tools=[tool], # google-genai-compatible
automatic_function_calling=types.AutomaticFunctionCallingConfig(
disable=True
),
),
)
# Такая же логика, как в openai адаптере
if response.function_calls:
results = await adapter.process_function_calls(response.function_calls)
contents = [
types.Content(role="user", parts=[types.Part.from_text("What's the weather in London?")]),
response.candidates[0].content,
*results,
]
final_response = client.models.generate_content(
model="gemini-2.5-flash",
contents=contents,
config=types.GenerateContentConfig(tools=[tool]),
)
print(final_response.text)
asyncio.run(main())
Кому это может быть полезно
Мы писали очень много кастомных интеграций в рамках стартапа https://aimalabs.io - звонки + WhatsApp ИИ с кастомными действиями. У каждого энтерпрайз клиента есть свои системы, с которыми надо коннектиться ИИшке в реальном времени - СРМка, старая апишка, база данных и тп. Писать постоянные tools стало муторно, у нас образовались внутренние тулы для автоматизации этого процесса, их было двое и оба мы вывели в мир:
Сначала появился генератор + хостинг MCP серверов по спеке/описанию - https://mcphero.app, который позволяет генерировать MCP сервера под различные кейсы за минуты, что очень удобно, своеобразный lovable для MCP серверов.
Но в кусках проекта, где все было на openai - мы не могли использовать MCP.
openai поддерживает только следующий формат tools:
CALENDAR_GET_AVAILABLE_SLOTS_TOOL_DEFINITION = {
"type": "function",
"function": {
"name": "get_available_slots",
"strict": True,
"description": "Get available time slots for scheduling appointments. Returns a list of available time slots based on business hours and existing calendar events.",
"parameters": {
"type": "object",
"properties": {
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (inclusive)",
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (inclusive). If not provided, defaults to 7 days from start_date.",
},
},
"required": ["start_date"],
},
},
}
Проект был обмазан такими definitions. Это сложно поддерживать и не очень приятно типизируется. В итоге мы поизучали как же агентские библиотеки/проекты используют MCP под капотом, и истина была очень проста - они все конвертируют их в tools так или иначе, но не выносят эту часть в opensource. Поэтому тот mapper, что мы использовали внутри, был зарежилен как библиотека:
https://pypi.org/project/mcphero/
https://github.com/stepacool/mcphero
Фичи и Возникшие челленджи
Первое - поддержка нескольких серверов и разрешение коллизий. У серверов может быть tools с одинаковыми названиями - "search", "query", "find" и т.п. MCPHero имеет внутренню систему подстановки минимальных префиксов, чтобы не запутывать LLM всяческими anti_collision_hash, но в тоже время сохранить уникальность и смысловую нагрузку. Пример:
adapter = MCPToolAdapterOpenAI([
MCPServerConfig(url="https://api.mcphero.app/mcp/weather", name="weather"),
MCPServerConfig(url="https://api.mcphero.app/mcp/calendar", name="calendar"),
])
tools = await adapter.get_tool_definitions()
# "search" станет "weather__search" и "calendar__search"
Второе - гибкая обработка ошибок. Так как несколько МСП серверов, да даже один - это много вызовов к third party API, ошибки могут возникать. Есть режим "пропустить" ошибочные вызовы, есть режим "вернуть ИИшке детали ошибки", а есть - уронить программу целиком(raise Exception'а).
Третье - параллелизация. ИИ всегда возвращает список tool_calls, и хоть там обычно только один, их также может быть и несколько. Они могут вызываться параллельно.
Roadmap
Если у вас уже есть продакшен код на openai, но вы хотите MCP без переписывания архитектуры — MCPHero именно для этого.
# В openai нельзя вызвать completions с MCP сервераами
response = client.chat.completions.create(
model="gpt-4o",
messages=messages,
tools=tools, # tools - должны быть специальные dict'ы, не ссылки до MCP
# mcp_tools=my_mcs_tools # такого аргумента, к сожалению, нет
# mcp_servers=my_mcp_servers # такого аргумента, к сожалению, тоже нет
tool_choice="auto"
)
Из-за этого возникает нужда либо переписать все на agentic библотеки(pydantic_ai, langchain, agents и тп), которые поддерживают MCP сервера, либо же писать свои адаптеры, которые пройдутся по lifecycle MCP, а потом замепят это все в формат openai:
Initialize -> Authorize -> List MCP Tools -> map_MCP_tool_to_openai_tool() -> openai_call
Поддерживать такое не хочется, особенно учитывая, что потом надо делать обратный меппинг:
openai_response.tool_calls -> map_openai_tool_call_to_MCP_payload -> Call MCP Tool
Поддерживать такое желания нет, каких-либо решений в открытом доступе найдено не было.
Что MCPHero за библиотека?
У MCPHero одна задача - конвертировать и поддерживать mapping MCP в нативные ИИ либы и обратно, чтобы можно было использовать MCP как tools. Пример:
import asyncio
from openai import OpenAI
from mcphero import MCPToolAdapterOpenAI
async def main():
adapter = MCPToolAdapterOpenAI("https://api.mcphero.app/mcp/your-server-id")
# Здесь мы получаем тулы из MCP сервера, но сразу в формате openai
tools = await adapter.get_tool_definitions()
messages = [{"role": "user", "content": "What's the weather in London?"}]
response = client.chat.completions.create(
model="gpt-4o",
messages=messages,
tools=tools, # openai не знает, что это MCP tools, он вызывает "свои"
)
if response.choices[0].message.tool_calls:
tool_results = await adapter.process_tool_calls(
response.choices[0].message.tool_calls
) # тут MCPHero обрабатывает openai tool_calls,
# вызывая MCP сервер по HTTP по его tools
messages.append(response.choices[0].message)
messages.extend(tool_results) # результаты тоже openai формата
final_response = client.chat.completions.create(
model="gpt-4o",
messages=messages,
tools=tools,
)
print(final_response.choices[0].message.content)
asyncio.run(main())
Также есть поддержка другой "немспшной" либы - google-genai (gemini)
import asyncio
from google import genai
from google.genai import types
from mcphero import MCPToolAdapterGemini
async def main():
adapter = MCPToolAdapterGemini("https://api.mcphero.app/mcp/your-server-id")
client = genai.Client(api_key="your-api-key")
# Один тул(можно и get_tool_definitions())
tool = await adapter.get_tool()
response = client.models.generate_content(
model="gemini-2.5-flash",
contents="What's the weather in London?",
config=types.GenerateContentConfig(
tools=[tool], # google-genai-compatible
automatic_function_calling=types.AutomaticFunctionCallingConfig(
disable=True
),
),
)
# Такая же логика, как в openai адаптере
if response.function_calls:
results = await adapter.process_function_calls(response.function_calls)
contents = [
types.Content(role="user", parts=[types.Part.from_text("What's the weather in London?")]),
response.candidates[0].content,
*results,
]
final_response = client.models.generate_content(
model="gemini-2.5-flash",
contents=contents,
config=types.GenerateContentConfig(tools=[tool]),
)
print(final_response.text)
asyncio.run(main())
Кому это может быть полезно
1. Командам с production-кодом на openai / google-genai
где responses / chat.completions уже глубоко и легаси
и любое "давайте перепишем на langchain" = нереализуемая хотелка
MCPHero позволяет добавить MCP без рефакторинга архитектуры
CRM / ERP / billing / legacy API
куча похожих tool definitions
постоянные изменения схем
Вынести tools в MCP сервер = меньше дублирования, меньше регрессий, чище код
Есть личный опыт как я удалял pydantic-ai из всего проекта и переписывал из-за его не готовности к production, не хотите повторить - сидите на openai
MCPHero — не фреймворк, а glue layer, особенно для openrouter и тп проектов
P.S если нужна генерация класнных MCP серверов с хостингом - попробуйте нашу облачную платформу https://mcphero.app - "lovable для MCP" - качественная генерация под любую спеку/АПИ/схему с поддержкой эфемерных переменных окружения, on-prem деплоя если надо и много другого.
Мы писали очень много кастомных интеграций в рамках стартапа https://aimalabs.io - звонки + WhatsApp ИИ с кастомными действиями. У каждого энтерпрайз клиента есть свои системы, с которыми надо коннектиться ИИшке в реальном времени - СРМка, старая апишка, база данных и тп. Писать постоянные tools стало муторно, у нас образовались внутренние тулы для автоматизации этого процесса, их было двое и оба мы вывели в мир:
Сначала появился генератор + хостинг MCP серверов по спеке/описанию - https://mcphero.app, который позволяет генерировать MCP сервера под различные кейсы за минуты, что очень удобно, своеобразный lovable для MCP серверов.
Но в кусках проекта, где все было на openai - мы не могли использовать MCP.
openai поддерживает только следующий формат tools:
CALENDAR_GET_AVAILABLE_SLOTS_TOOL_DEFINITION = {
"type": "function",
"function": {
"name": "get_available_slots",
"strict": True,
"description": "Get available time slots for scheduling appointments. Returns a list of available time slots based on business hours and existing calendar events.",
"parameters": {
"type": "object",
"properties": {
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (inclusive)",
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (inclusive). If not provided, defaults to 7 days from start_date.",
},
},
"required": ["start_date"],
},
},
}
Проект был обмазан такими definitions. Это сложно поддерживать и не очень приятно типизируется. В итоге мы поизучали как же агентские библиотеки/проекты используют MCP под капотом, и истина была очень проста - они все конвертируют их в tools так или иначе, но не выносят эту часть в opensource. Поэтому тот mapper, что мы использовали внутри, был зарежилен как библиотека:
https://pypi.org/project/mcphero/
https://github.com/stepacool/mcphero
Фичи и Возникшие челленджи
Первое - поддержка нескольких серверов и разрешение коллизий. У серверов может быть tools с одинаковыми названиями - "search", "query", "find" и т.п. MCPHero имеет внутренню систему подстановки минимальных префиксов, чтобы не запутывать LLM всяческими anti_collision_hash, но в тоже время сохранить уникальность и смысловую нагрузку. Пример:
adapter = MCPToolAdapterOpenAI([
MCPServerConfig(url="https://api.mcphero.app/mcp/weather", name="weather"),
MCPServerConfig(url="https://api.mcphero.app/mcp/calendar", name="calendar"),
])
tools = await adapter.get_tool_definitions()
# "search" станет "weather__search" и "calendar__search"
Второе - гибкая обработка ошибок. Так как несколько МСП серверов, да даже один - это много вызовов к third party API, ошибки могут возникать. Есть режим "пропустить" ошибочные вызовы, есть режим "вернуть ИИшке детали ошибки", а есть - уронить программу целиком(raise Exception'а).
Третье - параллелизация. ИИ всегда возвращает список tool_calls, и хоть там обычно только один, их также может быть и несколько. Они могут вызываться параллельно.
Roadmap
streaming / async tool_calls - обработка тяжелых тулов в бекграунде, не блокируя основной интерпретатор, стриминг
Больше библиотек, сейчас только openai и google-genai
Возможно переписать интерфейс, чтобы выглядел более "магически" - много магии под капотом, очень implicit, но сейчас такая мода/meta. Что-то типа
MCPHero.from_url("example.com/mcp").as_openai_tools()
Привести opensource проект в более приличный вид
Если у вас уже есть продакшен код на openai, но вы хотите MCP без переписывания архитектуры — MCPHero именно для этого.
