automcp

🚀 개요 (Overview)

automcp를 사용하면 기존 에이전트 프레임워크의 도구(tools), 에이전트(agents), 오케스트레이터(orchestrators)를 MCP 서버로 쉽게 변환할 수 있으며, 이를 통해 Cursor 및 Claude Desktop과 같은 클라이언트를 통해 표준화된 인터페이스로 접근할 수 있습니다.

현재 다음과 같은 에이전트 프레임워크에 대해 에이전트, 도구, 오케스트레이터를 MCP 서버로 배포하는 것을 지원합니다:

1. CrewAI
2. LangGraph
3. Llama Index
4. OpenAI Agents SDK
5. Pydantic AI
6. mcp-agent

🔧 설치 (Installation)

PyPI에서 설치:

# 기본 설치
pip install naptha-automcp

...

또는 소스에서 설치:

git clone https://github.com/napthaai/automcp.git
cd automcp
uv venv 
...

🧩 빠른 시작 (Quick Start)

프로젝트를 위한 새로운 MCP 서버를 생성합니다:

에이전트 구현이 포함된 프로젝트 디렉토리로 이동합니다:

cd your-project-directory

다음 플래그 중 하나(crewai, langgraph, llamaindex, openai, pydantic, mcp_agent)를 사용하여 CLI를 통해 MCP 서버 파일을 생성합니다:

automcp init -f crewai

생성된 run_mcp.py 파일을 편집하여 에이전트를 구성합니다:

# 이 임포트 문들을 실제 에이전트 클래스로 교체하세요
from your_module import YourCrewClass

...

의존성을 설치하고 MCP 서버를 실행합니다:

automcp serve -t sse

📁 생성된 파일 (Generated Files)

automcp init -f <FRAMEWORK>를 실행하면 다음 파일이 생성됩니다:

run_mcp.py

이 파일은 MCP 서버를 설정하고 실행하는 메인 파일입니다. 다음 내용을 포함합니다:

• 서버 초기화 코드
• STDIO 및 SSE 전송 핸들러 (transport handlers)
• 에이전트 구현을 위한 플레이스홀더 (placeholder)
• STDIO 프로토콜을 손상시킬 수 있는 경고를 억제하기 위한 유틸리티

다음 작업을 위해 이 파일을 편집해야 합니다:

• 에이전트/크루(crew) 클래스 임포트
• 입력 스키마(input schema) 정의 (에이전트가 허용하는 파라미터)
• 에이전트를 사용하여 어댑터(adapter) 구성

🔍 예시 (Examples)

예시 실행하기

저장소에는 지원되는 각 프레임워크에 대한 예시가 포함되어 있습니다:

# 저장소 클론 (Clone the repository)
git clone https://github.com/NapthaAI/automcp.git
cd automcp
...

각 예시는 일반적인 프로젝트와 동일한 워크플로 (workflow)를 따릅니다:

1. automcp init -f <FRAMEWORK>를 실행하여 서버 파일 생성
2. run_mcp.py를 편집하여 예시 에이전트 (agent)를 임포트 (import) 및 구성
3. 필요한 환경 변수 (environmental variables)가 포함된 .env 파일 추가
4. 의존성 (dependencies)을 설치하고 automcp serve -t sse를 사용하여 서비스 제공

CrewAI 예시

CrewAI 예시에 대해 전형적으로 구성된 run_mcp.py의 모습은 다음과 같습니다:

import warnings
from typing import Any
from automcp.adapters.crewai import create_crewai_adapter
...

🔄 MCP 서버 실행하기 (Running Your MCP Server)

파일 설정을 마친 후, 다음 방법 중 하나를 사용하여 서버를 실행할 수 있습니다:

# automcp CLI 사용
automcp serve -t stdio    # STDIO 전송 (transport)
automcp serve -t sse      # SSE 전송 (transport)
...

전송 모드 (transport modes)에 관한 참고 사항:

• STDIO: 서버를 수동으로 실행할 필요가 없습니다. 클라이언트 (Cursor)에 의해 시작됩니다.
• SSE: 다음의 2단계 프로세스로 진행됩니다:
  1. 서버를 별도로 시작: python run_mcp.py sse 또는 automcp serve -t sse
  2. 실행 중인 서버에 연결하기 위해 mcp.json 설정을 추가

uv run 명령어를 사용하고 싶다면, pyproject.toml에 다음 내용을 추가하세요:

[tool.uv.scripts]
serve_stdio = "python run_mcp.py"
serve_sse = "python run_mcp.py sse"

☁️ Naptha의 MCPaaS로 배포하기

Naptha는 새로 생성한 MCP 서버를 우리의 MCPaaS (MCP servers-as-a-service) 플랫폼에 배포하는 것을 지원합니다! 시작하기 매우 쉽습니다.

설정 (Setup)

Naptha의 MCPaaS 플랫폼은 저장소가 uv로 설정되어 있어야 합니다.
이는 pyproject.toml에 몇 가지 구성이 필요함을 의미합니다.

먼저, naptha-automcp에 의해 생성된 run_mcp.py 파일이 저장소의 루트 (root)인지 확인하세요.

둘째, pyproject.toml에 다음과 같은 구성이 포함되어 있는지 확인하세요:

[build-system]
requires = [ "hatchling",]
build-backend = "hatchling.build"
...

만약 에이전트가 저장소의 하위 디렉터리 또는 패키지 내에 있는 경우:

pyproject.toml
run_mcp.py
my_agent/
...

run_mcp.py에서 다음과 같이 임포트(import)되는지 확인하세요:

from my_agent.agent

아래와 같이 작성하면 빌드(build)가 실패하므로 주의하세요:

from .my_agent.agent

모든 설정을 마쳤다면, 코드를 커밋(commit)하고 GitHub에 푸시(push)하세요 (단, 환경 변수는 푸시하지 마세요!). 그 다음, 모든 설정이 올바르게 되었는지 테스트할 수 있습니다:

uvx --from https://github.com/your-username/your-repo serve_sse

이 명령을 실행했을 때 MCP 서버가 8000번 포트에서 성공적으로 실행된다면, 모든 준비가 완료된 것입니다!

서버 실행하기

1. labs.naptha.ai로 이동합니다.
2. GitHub 계정으로 로그인합니다.
3. 저장소 목록에서 수정한 저장소를 선택합니다. (GitHub 저장소를 자동으로 탐색합니다.)
4. OPENAI_API_KEY 등 환경 변수(environment variables)를 추가합니다.
5. Launch를 클릭합니다.
6. SSE URL을 복사하여 MCP 클라이언트(client)에 붙여넣습니다.

🔌 MCP 클라이언트와 함께 사용하기

Cursor

Cursor IDE와 통합하려면, 프로젝트 루트(root)에 .cursor 폴더를 생성하고 다음과 같은 설정이 담긴 mcp.json 파일을 추가하세요:

{
    "mcpServers": {
        "crew-name-stdio": {
...

참고: 모든 플레이스홀더(placeholder) 경로를 실제 파일 및 디렉터리의 절대 경로(absolute paths)로 반드시 교체해야 합니다.

GitHub 직접 실행

프로젝트를 GitHub에 푸시한 후 다음을 사용하세요:

{
   "mcpServers": {
       "My Agent": {
...

🛠️ 새로운 어댑터(Adapters) 생성하기

새로운 에이전트 프레임워크(agent framework)에 대한 지원을 추가하고 싶으신가요? 방법은 다음과 같습니다:

1. automcp/adapters/에 새로운 어댑터 파일을 생성하거나(또는 기존 프레임워크 파일에 추가하거나):

# automcp/adapters/framework.py
import json
import contextlib
...

2. examples/your_framework/에 예제를 생성합니다.

📝 참고 사항

• STDIO 전송 (STDIO transport) 방식을 사용할 때는 에이전트 코드 내의 print 문을 주의해야 합니다. 이는 프로토콜을 손상시킬 수 있습니다.
• 디버깅을 위해 MCP Inspector를 사용할 수 있습니다: npx @modelcontextprotocol/inspector
• STDIO 모드의 경우, 클라이언트(Cursor 등)가 사용자를 대신하여 서버를 시작한다는 점을 기억하세요.
• SSE 모드의 경우, 서버를 수동으로 시작한 다음 클라이언트가 서버에 연결하도록 설정해야 합니다.