커스터마이즈 MCP 서버를 구축하는 방법 (오픈 소스)

커서 IDE에 슈퍼파워를 부여하는 상상을 해보세요 - 웹을 자동으로 검색하거나 문서를 분석하는 기능을 통해 편집기를 떠나지 않고도 가능합니다. 이 튜토리얼에서는 이러한 기능을 커서에 추가하는 맞춤형 MCP(모델 컨텍스트 프로토콜) 서버를 만드는 방법에 대해 설명합니다.

맞춤형 MCP 서버를 구축해야 하는 이유는?

MCP 서버를 사용하면 커서의 기능을 기본 기능을 넘어 확장할 수 있습니다. 자신의 MCP 서버를 사용하면:

• 웹 검색 기능 추가
• 문서 분석 도구 만들기 (RAG)
• 전문 API 연결
• 맞춤형 AI 작업 흐름 구축

최근 업데이트로 MCP 서버 개발이 그 어느 때보다 쉬워졌습니다 - 초보자에게 완벽합니다!

1단계: 개발 환경 설정

전제 조건

시작하기 전에 다음이 준비되어 있는지 확인하세요:

1. Cursor IDE (최신 버전)
2. Python 3.8+ 설치
3. UV 패키지 관리자 (아래에서 설치할 것입니다)
4. 터미널 명령어에 대한 기본적인 이해

시작 템플릿 가져오기

우리는 빠르게 시작하기 위해 기성 템플릿을 사용할 것입니다:

1. 저장소 복제:

git clone https://github.com/patchy631/ai-engineering-hub/tree/main/cursor_linkup_mcp

1. Cursor IDE에서 폴더 열기

2단계: Cursor에서 MCP 서버 설정

Cursor에서 다음으로 이동하세요:

설정 > 커서 설정 > MCP > 새로운 MCP 서버 추가

서버를 구성하세요:

• 이름: 설명적인 이름을 부여하세요 (예: "twitter-demo")
• 명령어: UV 패키지 관리자를 사용할 것입니다

UV가 설치되어 있지 않은 경우:

pip install uv

서버를 실행할 명령어를 설정하세요:

uv --directory /path/to/cursor_linkup_mcp run server.py

(/path/to/를 저장소를 복제한 실제 위치로 교체하세요)

"추가"를 클릭하여 구성 내용을 저장합니다.

3단계: 새로운 도구 테스트

서버가 설정되었으므로, 이제 기능을 테스트해 보겠습니다:

1. 웹 검색 도구

이는 커서가 질문에 대한 답을 웹에서 검색할 수 있게 해줍니다.

사용 방법:

1. "에이전트" 모드에서 새 채팅 열기

2. 웹 조회가 필요한 질문을 하세요, 예를 들어:

>> 인도와 호주의 최신 크리켓 경기에서 누가 이겼나요?

3. 커서는 MCP 서버를 사용하여 답을 찾아 표시합니다.

2. RAG (문서 분석) 도구

이는 커서가 개인 문서를 분석할 수 있게 해줍니다.

설정 방법:

1. 복제한 저장소에서 data 폴더를 찾습니다.

2. 분석할 문서(PDF, Word 파일 등)를 추가합니다.

3. 채팅에서 문서에 대해 질문하세요:

>> DeepSeek R1이 훈련된 방법에 대한 내 파일의 주요 내용을 요약해 주세요.

결과를 확인하세요:

작동 방식

당신의 MCP 서버는 커서와 외부 서비스 간의 다리 역할을 합니다:

1. 질문을 할 때, 커서는 그것을 MCP 서버로 보냅니다.
2. 서버는 요청을 처리합니다 (웹 검색 또는 문서 분석)
3. 결과는 커서로 돌려져 표시됩니다.

MCP 서버 코드 이해하기

이 Python 스크립트는 두 가지 강력한 AI 도구를 커서에 추가하는 맞춤형 MCP(모델 컨텍스트 프로토콜) 서버를 생성합니다: 웹 검색 및 문서 분석 (RAG). 각 부분이 수행하는 작업을 분해해 봅시다:

1. 의존성 가져오기

import asyncio
from dotenv import load_dotenv
from linkup import LinkupClient
from rag import RAGWorkflow
from mcp.server.fastmcp import FastMCP

• asyncio: 비동기 작업을 가능하게 함 (여러 요청을 효율적으로 처리하는 데 중요)
• dotenv: .env 파일에서 환경 변수를 로드함 (API 키 등)
• LinkupClient: 웹 검색 기능을 처리함
• RAGWorkflow: 문서 분석을 관리함 (Retrieval-Augmented Generation)
• FastMCP: 핵심 MCP 서버 프레임워크

2. 초기 설정

load_dotenv()

mcp = FastMCP('linkup-server')
client = LinkupClient()
rag_workflow = RAGWorkflow()

• load_dotenv(): .env 파일에서 민감한 설정을 로드함 (API 키 등)
• mcp: "linkup-server"라는 이름의 주요 MCP 서버 인스턴스를 생성함
• client: 웹 검색 도구를 초기화함
• rag_workflow: 문서 분석 시스템을 준비함

3. 웹 검색 도구

@mcp.tool()
def web_search(query: str) -> str:
    """주어진 쿼리에 대해 웹을 검색합니다."""
    search_response = client.search(
        query=query,
        depth="standard",  # "standard" 또는 "deep"
        output_type="sourcedAnswer",  # 옵션: "searchResults", "sourcedAnswer", 또는 "structured"
        structured_output_schema=None,  # output_type="structured"일 경우 필요
    )
    return search_response

이것이 하는 일:

• 커서 IDE에 web_search라는 도구를 추가함
• 검색 query를 입력받음 (예: "파리의 현재 날씨")
• 다양한 유형의 검색을 수행할 수 있음:
• standard vs deep (검색의 철저함)
• 원시 결과(searchResults) 또는 처리된 답변(sourcedAnswer) 중 하나를 반환함
• 검색 결과를 커서로 반환함

커서에서의 예시 사용:

/web_search query="2023 크리켓 월드컵에서 누가 이겼나요?"

4. 문서 분석 (RAG) 도구

@mcp.tool()
async def rag(query: str) -> str:
    """데이터 디렉토리의 문서를 사용하여 쿼리에 답변하는 RAG를 사용합니다."""
    response = await rag_workflow.query(query)
    return str(response)

이것이 하는 일:

• rag라는 도구(문서 검색 보강 생성)를 생성함
• /data 폴더에 배치한 문서를 분석함
• 해당 문서를 기반으로 질문에 답변함
• 큰 파일과 함께 원활하게 작동하기 위해 비동기적으로 작업함

커서에서의 예시 사용:

/rag query="이 AI 논문의 주요 안전 권고 사항은 무엇인가요?"

5. 서버 시작

if __name__ == "__main__":
    asyncio.run(rag_workflow.ingest_documents("data"))
    mcp.run(transport="stdio")

이 코드를 실행하면 발생하는 일:

1. 먼저 data 폴더의 모든 문서를 메모리로 로드합니다.
2. 표준 입력/출력 통신을 사용하여 MCP 서버를 시작합니다.
3. 두 도구 모두를 커서에서 사용할 수 있게 해줍니다.

MCP 서버 구현의 주요 기능

1. 보안: 민감한 데이터에 .env 사용
2. 유연성: 다양한 검색 모드 제공 (표준/심화)
3. 로컬 처리: 클라우드에 전송하지 않고 개인 문서를 분석
4. 성능: 매끄러운 경험을 위한 비동기 작업 사용

커서가 이 서버를 사용하는 방법

1. 커서에서 명령어를 입력합니다 (예: /web_search)
2. 커서는 이 실행 중인 서버에 쿼리를 보냅니다.
3. 서버가 이를 처리합니다 (웹 검색 또는 문서 분석)
4. 결과가 커서에 반환되어 사용자에게 표시됩니다.

이렇게 하면 커서 IDE가 웹을 검색하고 개인 문서를 분석할 수 있는 강력한 연구 도우미로 변신합니다 - 모든 것이 간단한 채팅 명령을 통해 가능합니다!

문제 해결 팁

문제가 발생하는 경우:

1. UV 명령이 올바른 위치를 가리키는지 확인하세요.
2. 모든 종속성이 설치되었는지 확인하세요 (명령어 pip install -r requirements.txt 실행)
3. Python 버전이 3.8 이상인지 확인하세요.
4. 서버가 시작되지 않으면 커서의 오류 로그를 확인하세요.

다음 단계:

기본 MCP 서버가 실행 중이므로, 다음을 할 수 있습니다:

• 더 많은 도구 추가 (예: 트위터 API 통합)
• 웹 검색 파라미터 사용자 정의
• 더 나은 프롬프트로 문서 분석 개선
• 팀원과 서버 공유

마지막 생각

첫 번째 MCP 서버를 구축하는 것이 벅찰 듯 보일 수 있지만, 보시다시피 템플릿 덕분에 간단합니다. 30분도 안 되어 주문형 기능을 커서에 추가하여 수작업 시간을 절약할 수 있게 되었습니다.

다음에는 어떤 것을 만들 것인가요? 아마도:

• 주식 가격 확인
• 코드베이스 검색
• 소셜 미디어 게시물 생성

가능성은 무궁무진합니다! 모든 전문가도 한때는 초보자였습니다 - 이제 MCP 서버 개발의 세계로 첫 발을 내디뎠습니다.

그리고 하는 김에, Apidog를 확인하여 MCP 및 API 개발 작업 흐름을 강화하는 것도 잊지 마세요! 🚀