🚀 Простой сервер инструментов на FastAPI

Лёгкий сервер инструментов на базе FastAPI, который предоставляет простые служебные функции через REST API-эндпоинты.

Этот проект демонстрирует, как Python-функции можно обернуть в FastAPI-эндпоинты и обращаться к ним через HTTP-запросы. Он также служит базовой основой для понимания того, как аналогичные инструменты в дальнейшем могут быть предоставлены через Model Context Protocol (MCP).

📌 Возможности

• ➕ Сложение двух чисел

• 🕐 Получение текущей даты и времени

• 📝 Подсчёт слов в заданном тексте

• ⚡ Быстрая разработка API с помощью FastAPI

• ✅ Валидация запросов с помощью Pydantic

• 📦 Ответы API в формате JSON

• 📖 Автоматическая интерактивная документация API

• 🔌 Простая архитектура, которую можно расширить до сервера инструментов на базе MCP

Related MCP server: SENTRA MCP

🏗️ Структура проекта

simple-tool-server-fastapi/
│
├── main.py              # FastAPI application and API endpoints
├── model.py             # Pydantic request models
├── tools.py             # Core utility functions
├── requirements.txt     # Project dependencies
├── .gitignore           # Files excluded from Git
└── README.md            # Project documentation

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

Проект работает по простой схеме:

Client
   ↓
FastAPI Endpoint
   ↓
Python Tool Function
   ↓
JSON Response

Например:

GET /add
   ↓
add_numbers()
   ↓
JSON response

Ту же концепцию в дальнейшем можно расширить до архитектуры MCP:

AI Assistant
     ↓
MCP Client
     ↓
MCP Server
     ↓
Python Tools

🛠️ Используемые технологии

• Python

• FastAPI

• Pydantic

• Uvicorn

• REST API

• JSON

• Концепции Model Context Protocol (MCP)

⚙️ Установка

1. Клонируйте репозиторий

git clone https://github.com/sejalpatole/simple-tool-server-fastapi.git

2. Перейдите в проект

cd simple-tool-server-fastapi

3. Создайте виртуальное окружение

python -m venv venv

4. Активируйте виртуальное окружение

Windows

venv\Scripts\activate

macOS / Linux

source venv/bin/activate

5. Установите зависимости

pip install -r requirements.txt

▶️ Запуск приложения

Запустите сервер FastAPI с помощью Uvicorn:

uvicorn main:app --reload

Сервер запустится по адресу:

http://127.0.0.1:8000

📖 Документация API

FastAPI автоматически предоставляет интерактивную документацию API.

Swagger UI

Откройте:

http://127.0.0.1:8000/docs

ReDoc

Откройте:

http://127.0.0.1:8000/redoc

🔌 Эндпоинты API

1. Главная страница

Эндпоинт

GET /

Возвращает информацию о доступных эндпоинтах.

Пример ответа

{
  "message": "Welcome to the Simple Tool Server",
  "available_endpoints": [
    "/add",
    "/time",
    "/wordcount"
  ]
}

2. Сложение двух чисел

Эндпоинт

GET /add

Параметры

Пример

http://127.0.0.1:8000/add?a=10&b=20

Пример ответа

{
  "operation": "Addition",
  "a": 10,
  "b": 20,
  "result": 30
}

3. Получение текущего времени

Эндпоинт

GET /time

Пример

http://127.0.0.1:8000/time

Пример ответа

{
  "current_time": "2026-08-20 21:00:00"
}

4. Подсчёт слов

Эндпоинт

POST /wordcount

Тело запроса

{
  "text": "FastAPI is easy to use"
}

Пример ответа

{
  "text": "FastAPI is easy to use",
  "word_count": 5
}

🧩 Компоненты проекта

main.py

Содержит приложение FastAPI и маршруты API.

В нём определены эндпоинты для:

• /

• /add

• /time

• /wordcount

tools.py

Содержит основные служебные функции Python:

add_numbers()
get_current_time()
word_count()

Разделение логики инструментов и уровня API упрощает поддержку и расширение проекта.

model.py

Содержит модель Pydantic, используемую для валидации запроса /wordcount.

class WordCountRequest(BaseModel):
    text: str

Это гарантирует, что API получает ожидаемую структуру запроса.

🧪 Тестирование

API можно тестировать с помощью:

• Swagger UI

• Postman

• Браузера

• cURL

• Любого REST API-клиента

Swagger UI доступен по адресу:

http://127.0.0.1:8000/docs

🌱 Планы по улучшению

Возможные будущие расширения включают:

• Добавление дополнительных служебных инструментов

• Добавление аутентификации

• Добавление логирования

• Добавление автоматических тестов с помощью Pytest

• Добавление поддержки Docker

• Добавление поддержки протокола MCP

• Предоставление Python-инструментов через MCP-сервер

• Добавление инструментов на основе базы данных

• Развёртывание сервера в облачной платформе

🎯 Результаты обучения

В рамках этого проекта демонстрируются следующие концепции:

• Создание API с помощью FastAPI

• Создание GET и POST эндпоинтов

• Валидация запросов с помощью Pydantic

• Разделение логики API и бизнес-логики

• Работа с JSON-запросами и ответами

• Запуск приложений с помощью Uvicorn

• Понимание основ инструментальных ИИ-систем

• Понимание взаимосвязи между API, инструментами и MCP

👩💻 Автор

Sejal Patole

⭐ Благодарность

Этот проект был разработан в качестве учебного упражнения для понимания FastAPI, REST API, служебных инструментов Python и основ архитектуры инструментов на базе MCP.

Если вы нашли этот проект полезным, поставьте репозиторию ⭐.