🚀 FastAPI 기반 간단한 도구 서버

간단한 유틸리티 함수를 REST API 엔드포인트로 노출하는 경량 FastAPI 기반 도구 서버입니다.

이 프로젝트는 Python 함수를 FastAPI 엔드포인트 뒤에 래핑하여 HTTP 요청을 통해 접근하는 방법을 보여줍니다. 또한 유사한 도구가 나중에 **Model Context Protocol (MCP)**을 통해 노출될 수 있는 방법을 이해하기 위한 기초를 제공합니다.

📌 기능

• ➕ 두 숫자 더하기

• 🕐 현재 날짜 및 시간 가져오기

• 📝 주어진 텍스트의 단어 수 세기

• ⚡ FastAPI를 사용한 빠른 API 개발

• ✅ Pydantic을 사용한 요청 검증

• 📦 JSON 기반 API 응답

• 📖 자동 대화형 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

▶️ 애플리케이션 실행

Uvicorn을 사용하여 FastAPI 서버를 시작합니다:

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

/wordcount 요청을 검증하는 데 사용되는 Pydantic 모델을 포함합니다.

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 프로토콜 지원 추가

• MCP 서버를 통해 Python 도구 노출

• 데이터베이스 기반 도구 추가

• 클라우드 플랫폼에 서버 배포

🎯 학습 성과

이 프로젝트를 통해 다음 개념이 시연됩니다:

• FastAPI로 API 구축

• GET 및 POST 엔드포인트 생성

• Pydantic을 사용한 요청 검증

• API 로직과 비즈니스 로직 분리

• JSON 요청 및 응답 처리

• Uvicorn으로 애플리케이션 실행

• 도구 기반 AI 시스템의 기초 이해

• API, 도구, MCP 간의 관계 이해

👩💻 작성자

Sejal Patole

⭐ 감사의 글

이 프로젝트는 FastAPI, REST API, Python 유틸리티 도구, MCP 기반 도구 아키텍처의 기초를 이해하기 위한 학습 연습 프로젝트로 개발되었습니다.

이 프로젝트가 유용하다고 생각되면 저장소에 ⭐을 눌러주세요.