mcpforge

Запустите MCP-сервер на 5 строках Python.

Before                              After
──────                              ─────
~200 lines of                       @serve
JSON-RPC stdio                      class MarketTools:
boilerplate, schema                     @tool
generation, error                       def latest_price(self, symbol: str) -> float: ...
handling, lifecycle                     @tool
management.                             def search(self, query: str) -> list[dict]: ...

                                    $ python -m mcpforge run market:MarketTools
                                    ✓ MCP server running on stdio

Почему mcpforge

Model Context Protocol (MCP) — это открытый стандарт, который Claude, Cursor и растущая экосистема ИИ-инструментов используют для вызова внешних функций. Это мощно — но написание сервера в настоящее время является мучением.

Вы пишете один и тот же JSON-RPC фрейминг, генерацию схемы, цикл диспетчеризации и обработку ошибок в каждом проекте. mcpforge стирает всё это. Аннотируйте свой класс. Укажите типы для своих методов. Готово.

from mcpforge import serve, tool

@serve(name="market_tools", version="0.1.0")
class MarketTools:
    """Market data tools for AI agents."""

    @tool(description="Get the latest price for a symbol")
    def latest_price(self, symbol: str) -> float:
        return fetch_price(symbol)

    @tool
    def search(self, query: str, limit: int = 10) -> list[dict]:
        """Search ticker symbols matching `query`."""
        return run_search(query, limit)

Это полноценный, соответствующий спецификации MCP-сервер. Подсказки типов превращаются в JSON Schema. Docstrings становятся описаниями инструментов. Возвращаемые значения автоматически сериализуются.

60-секундный быстрый старт

pip install mcpforge

# hello.py
from mcpforge import serve, tool

@serve(name="hello", version="0.1.0")
class HelloTools:
    @tool
    def greet(self, name: str = "world") -> str:
        """Say hello to someone."""
        return f"Hello, {name}!"

python -m mcpforge run hello:HelloTools

Теперь у вас есть работающий MCP-сервер, общающийся по JSON-RPC 2.0 через stdio.

Как это работает

1. @serve помечает класс как MCP-сервер (имя, версия, возможности).

2. @tool регистрирует методы как инструменты MCP.

3. @resource(uri=...) регистрирует методы как ресурсы MCP.

4. mcpforge анализирует сигнатуру каждого метода и создает JSON Schema — примитивы, list[T], dict[str, T], Literal[...], Optional[T], датаклассы и модели Pydantic — всё это просто работает.

5. python -m mcpforge run mod:Class запускает цикл stdio, обрабатывает initialize / tools/list / tools/call / resources/list / resources/read, и сообщает об ошибках JSON-RPC с соответствующими кодами.

Никакого внешнего SDK MCP. Только стандартная библиотека json + pydantic для удобства работы со схемами.

Встроенные серверы

Два готовых сервера, которые вы можете использовать уже сегодня:

# Filesystem tools (sandboxed to a root directory)
python -m mcpforge run mcpforge.builtin.filesystem:FilesystemTools

# HTTP fetch tools
python -m mcpforge run mcpforge.builtin.http:HttpTools

FilesystemTools предоставляет list_dir, read_file, search — в песочнице с проверками обхода путей. HttpTools предоставляет fetch_url с ограничениями по размеру.

Подключение к Claude Desktop

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "market": {
      "command": "python",
      "args": ["-m", "mcpforge", "run", "market:MarketTools"],
      "cwd": "/path/to/your/project"
    }
  }
}

Перезапустите Claude Desktop. Ваши инструменты появятся в диалоге.

Подключение к Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "market": {
      "command": "python",
      "args": ["-m", "mcpforge", "run", "market:MarketTools"]
    }
  }
}

Сравнение

Проверка формата передачи

python -m mcpforge inspect market:MarketTools

Выводит точную полезную нагрузку tools/list, которую увидят ваши клиенты.

Дорожная карта

• [x] Инструменты (вызов, список)

• [x] Ресурсы (чтение, список)

• [x] Подсказки типов -> JSON Schema (Pydantic v2, датаклассы, Literal, Optional)

• [x] Встроенные серверы файловой системы и http

• [ ] Подписки на ресурсы

• [ ] Возможность подсказок (Prompts)

• [ ] Возможность сэмплирования

• [ ] Транспорт WebSocket / HTTP-SSE (опционально [http])

• [ ] Асинхронные инструменты (async def)

• [ ] Хуки трассировки OTel

Лицензия

MIT — см. LICENSE.

Автор: thechifura. Родственные проекты: quantflow и strategos.