Agent MCP

에이전트 MCP

조정되고 효율적인 AI 협업을 위해 MCP(Model Context Protocol)를 사용하여 다중 에이전트 시스템을 만드는 프레임워크입니다.

빠른 시작 가이드

참고: 위의 스크린샷처럼 동일한 코드베이스에서 여러 커서 창을 실행하려면 https://github.com/rinadelph/MultipleCursor를 사용하는 것이 좋습니다.

1. 설정 환경 :
   • 저장소를 복제하고 .env.example 을 .env 로 복사합니다.
   • OpenAI API 키를 .env 에 추가하세요
   • uv venv && uv pip install -e .
2. MCP 서버 시작 :지엑스피1중요 : 관리자 토큰은 프로젝트 컨텍스트의 .agent/mcp_state.db SQLite 데이터베이스에 저장됩니다. 액세스하려면 SQLite 뷰어 확장 프로그램을 설치하세요.
3. 주요 컨텍스트 문서(MCD) 생성 :
   • 시스템 아키텍처, API 경로, 데이터 모델 등을 포함한 자세한 MCD.md 만듭니다.
4. 관리 에이전트 실행 :
   • 한 창/세션에서 시작
   • 관리자 토큰을 제공하세요
5. 워커 에이전트 초기화 :
   • 각 작업자에 대해 새 창/세션 열기
   • 아래 섹션 4에서 자동 모드로 복사 작업자 프롬프트
   • 올바른 에이전트 ID 및 관리자 토큰으로 교체하세요.

자세한 내용은 아래의 자세한 지침을 따르세요.

특징

• 다중 에이전트 협업 프레임워크
• 업무 관리 및 조정
• 에이전트 간 컨텍스트 및 지식 공유
• 에이전트 상호 작용의 그래프 시각화
• 임베딩 및 RAG 기능 지원
• 작업, 에이전트 및 컨텍스트를 시각화하는 대화형 대시보드.

주요 컨텍스트 문서(MCD)를 사용한 프로젝트 계획

개발을 시작하기 전에 심층적인 조사를 통해 애플리케이션의 단일 정보 소스인 메인 컨텍스트 문서(MCD)를 작성하는 것이 필수적입니다. 이 문서는 다음과 같은 세부적인 계획을 제공합니다.

• 시스템 아키텍처 및 구성 요소 관계
• 모든 화면과 구성 요소에 대한 UI/UX 디자인
• API 경로 및 엔드포인트
• 데이터 구조 및 모델
• 구현 단위 및 작업
• 종속성 및 기술 스택

MCD가 중요한 이유는 다음과 같습니다.

1. 이를 통해 에이전트는 개별 구성 요소를 작업하기 전에 전체 시스템을 이해할 수 있습니다.
2. 선형적이고 조정된 건물(청사진으로 집을 짓는 것과 같음)이 가능합니다.
3. 구조화되고 관련성 있는 컨텍스트를 제공하여 토큰 사용을 줄입니다.
4. 에이전트 간의 충돌 구현을 방지합니다.

이 저장소의 MCD.md 파일을 검토하여 필요한 구조와 세부 정보 수준을 파악하십시오. MCD에는 다음이 포함되어야 합니다.

• 개요 및 목표
• 컨텍스트 및 아키텍처 다이어그램
• 기능적 요구 사항
• 디자인 사양(UI/UX, API, 데이터 모델)
• 구현 세부 사항
• 에이전트를 위한 작업 분류

포괄적인 MCD를 통해 상담원은 각 부분이 전체에 어떻게 들어맞는지 명확하게 이해한 후 신청서를 부분별로 구현할 수 있습니다.

설치

필수 조건

• 파이썬 3.8 이상
• uv (패키지 설치를 더 빠르게 하기 위해 권장)

설정

1. 저장소를 복제합니다.
   git clone https://github.com/your-username/agent-mcp.git cd agent-mcp
2. 예제 파일을 복사하여 환경 변수를 설정하세요.
   cp .env.example .env
3. .env 파일을 편집하고 OpenAI API 키를 추가하세요.
   OPENAI_API_KEY=your_openai_api_key_here
4. uv를 사용하여 설치:
   uv venv uv pip install -e .
   또는 pip를 사용하면:
   pip install -e .

다중 에이전트 워크플로

워크플로 개요

1. 심층 조사로 시작하세요 : 코딩하기 전에 AI를 사용하여 포괄적인 기본 컨텍스트 문서(MCD)를 만드는 데 도움을 받으세요.
2. 인프라 시작 : MCP 서버를 시작하고 데이터베이스에서 관리자 토큰을 찾습니다.
3. 관리자 에이전트 설정 : 토큰과 INSTRUCTIONS.md를 사용하여 관리자 에이전트를 초기화합니다.
4. 작업자 생성 : 관리자는 프로젝트의 다양한 측면에 대한 전문 작업자를 생성합니다.
5. 작업 할당 : 관리자는 MCD를 개별 작업으로 분할하고 작업자에게 할당합니다.
6. 병렬 개발 : 작업자는 MCP를 통해 컨텍스트를 공유하면서 작업을 실행합니다.
7. 컨텍스트 보존 : 모든 에이전트는 자신의 지식을 중앙 데이터베이스에 저장합니다.

개발 루프

아키텍처 개요

MCP 시스템은 다음과 같은 계층적 구조를 사용합니다.

• 관리 에이전트 : 다른 에이전트를 조정하고, 작업을 할당하고, 전반적인 프로젝트 방향을 유지합니다.
• 작업자 에이전트 : 특정 작업(프런트엔드, 백엔드, 데이터 모델링 등)을 실행하는 전문 에이전트

에이전트 설정 및 운영

1. MCP 서버 시작

옵션:

• --port : 서버를 실행할 포트(기본값: 8080)
• --project-dir : 프로젝트의 기본 디렉토리

2. 액세스 관리자 토큰

관리자 토큰은 MCP 서버에 대한 특권적인 액세스를 제공하며 모든 에이전트 작업에 필요합니다.

관리자 토큰 찾기 :

1. 서버를 시작하면 토큰이 자동으로 생성됩니다.
2. 이 토큰은 .agent/mcp_state.db SQLite 데이터베이스에 저장됩니다.
3. VS Code 또는 다른 SQLite 도구용 SQLite 뷰어 확장 프로그램 설치
4. 데이터베이스를 열고 project_context 테이블을 확인하세요.
5. 관리자 토큰 항목을 찾으세요

에이전트 토큰 : 에이전트별 토큰도 .agent 폴더에 저장됩니다. 이 토큰은 각 에이전트에게 MCP 시스템 내에서 고유한 권한과 ID를 부여합니다.

3. 에이전트 출시

1. 먼저 MCP 서버를 시작하세요 .
   uv run -m mcp_template.main --port 8080 --project-dir /path/to/your/project
   서버는 시작 시 관리자 토큰을 생성합니다. 에이전트 인증에 필요하므로 이 토큰을 저장해 두세요.
2. 관리 에이전트 : 다음을 사용하여 단일 관리 에이전트를 시작합니다.
   uv run -m mcp_template.mcp_client_runner --admin
   ModuleNotFoundError: No module named 'mcp_client' 와 같은 가져오기 오류가 발생하면 프로젝트 루트에서 실행하고 있고 Python 패키지가 제대로 설치되어 있는지 확인하세요.
3. 워커 에이전트 : 워커 에이전트를 직접 실행하는 대신, 관리자 에이전트에게 워커 에이전트를 생성하고 관리하도록 지시할 수 있습니다. 관리자 에이전트에게 다음과 같이 지시하면 됩니다.
   "Create a new agent with ID 'frontend-worker' and assign it to implement the login page based on the MCD."
   관리 에이전트는 작업자 에이전트에 대한 작업 생성 및 할당을 처리합니다.

4. Worker Agent와 함께 AUTO 모드 사용

워커 에이전트를 초기화하는 권장 방법은 관리 에이전트를 사용하는 것입니다. 에이전트가 생성되면 다음과 같은 워커 초기화 프롬프트를 사용하세요(복사하여 워커 에이전트에 붙여넣으세요).

[agent_id] 실제 작업자 ID(예: "frontend-worker")로 바꾸고 your_admin_token_here MCP 서버를 시작할 때 생성된 토큰으로 바꾸세요.

이 명령은 에이전트에게 다음을 수행하도록 지시합니다.

• 사용자 개입 없이 자율적으로 작동
• 작업 상태 추적을 통해 작업자 프로토콜을 따르세요
• 상호 작용 전반에 걸쳐 컨텍스트 유지를 위해 메모리 활용
• 작업 컨텍스트를 이해하기 위해 RAG 시스템에 사전에 쿼리를 보냅니다.

최상의 결과를 얻으려면 AUTO 명령 전에 INSTRUCTIONS.md의 지침을 복사하여 붙여넣어 에이전트를 초기화하세요.

계기반

http://localhost:8080 에서 대시보드에 접속하여 다음을 수행하세요.

• 실시간으로 에이전트 활동을 모니터링합니다
• 작업 상태 및 종속성 보기
• 에이전트 관계 및 조정을 관찰하세요
• 파일 작업 및 컨텍스트 공유 추적

대안 개발: 다중 에이전트 세션

복잡한 프로젝트에 권장되는 접근 방식은 다음과 같습니다.

1. 관리자 에이전트에 대해 하나의 대화를 사용하세요.
2. 각 작업자 에이전트에 대해 별도의 대화/세션을 시작합니다.
3. 모든 에이전트와 동일한 관리 토큰을 공유합니다.
4. 여러 창/세션에서 Claude Code, RooCode 또는 Cursor 사용

이러한 접근 방식은 공유 MCP 시스템을 통해 협업하는 동안 각 에이전트에게 고유한 대화 맥락을 제공합니다.

워크플로 예시:

1. MCP 서버를 시작하고 관리자 토큰을 기록하세요.
2. 한 창에서 관리자 에이전트 만들기
3. 각 작업자 에이전트에 대해 새 창을 열고 위의 작업자 프롬프트로 초기화합니다.
4. 각 작업자에게 고유한 에이전트 ID를 부여하지만 동일한 관리자 토큰을 부여합니다.

토큰 시스템 및 리소스 관리

토큰 이해

토큰은 MCP 시스템에서 여러 가지 목적을 위해 사용됩니다.

1. 인증 토큰 : 에이전트 식별 및 관리자 액세스에 사용됨
2. RAG 토큰 : 지식 기반에서 컨텍스트를 삽입하고 검색하는 데 사용됩니다.
3. OpenAI 토큰 : 에이전트 작업(모델 사용) 중에 소비됨

토큰 관리

토큰 사용을 모니터링하고 관리하려면:

1. SQLite Viewer 플러그인을 설치하거나 명령줄을 사용하세요.
   sqlite3 /path/to/project/.agent/mcp_state.db
2. 쿼리 토큰 사용:
   SELECT * FROM token_usage;
3. "리소스" 탭 아래의 대시보드에서 모니터링하세요.

리소스 최적화

대규모 프로젝트의 경우:

1. 컨텍스트 크기를 줄이기 위해 집중된 기능을 갖춘 전문 에이전트를 사용하세요.
2. 명확한 종속성을 통해 작업을 더 작은 단위로 분할합니다.
3. 효율적인 컨텍스트 검색을 위해 RAG 시스템 활용
4. 메시지에서 반복하는 대신 프로젝트 컨텍스트에서 공유 정보를 저장합니다.

RAG 프로젝트 및 지식 기반

프로젝트 RAG 설정

검색 증강 생성(RAG) 시스템을 사용하면 에이전트가 관련 프로젝트 지식에 효율적으로 액세스할 수 있습니다.

1. 인덱스 프로젝트 파일:
   python -m mcp_template.rag_indexer --project-dir /path/to/project
2. 지식 기반에 문서를 추가합니다.
   python -m mcp_template.rag_indexer --add-doc /path/to/document.md

에이전트 워크플로에서 RAG 사용

에이전트는 다음을 사용하여 지식 기반을 쿼리할 수 있습니다.

이렇게 하면 전체 파일을 로드하지 않고도 관련 컨텍스트를 반환하고, 토큰을 저장하며 응답 품질을 개선할 수 있습니다.

에이전트 작업 할당 전략

최적의 성능을 위해 다음 지침을 따르세요.

1. 작업 세분성 : 명확한 입력/출력을 통해 대규모 작업을 원자 단위로 분해합니다.
2. 종속성 추적 : 할당에서 작업 종속성을 명시적으로 정의합니다.
3. 역량 매칭 : 관련 역량을 갖춘 에이전트에게 작업 할당
4. 진행 상황 모니터링 : 명시적 상태 업데이트를 사용하여 작업 진행 상황을 추적합니다.
5. 컨텍스트 공유 : 나중에 조회할 때 필요한 컨텍스트를 할당 시점에 제공하여 검색 횟수를 줄입니다.

관리자에서 작업자로의 작업 할당 예:

새로운 작업자 에이전트를 생성할 때:

1. 관리자 에이전트에게 "ID가 'frontend-worker'인 새 에이전트를 만들고 MCD에 따라 로그인 페이지를 구현하도록 할당하세요."라고 말합니다.
2. 새 창/세션을 열고 앞서 설명한 AUTO 프롬프트로 작업자 에이전트를 초기화합니다.
3. 작업자가 할당된 작업에 액세스할 수 있도록 관리자 토큰을 포함해야 합니다.

구성 요소

• main.py : MCP 서버 구현
• mcp_client.py : 에이전트를 MCP에 연결하기 위한 클라이언트 라이브러리
• dashboard_api.py : 시각화를 위한 API 엔드포인트
• rag_agent_test.py : RAG 지원 에이전트의 예
• INSTRUCTIONS.md : 에이전트를 위한 운영 지침

환경 변수

• OPENAI_API_KEY : OpenAI API 키
• MCP_SERVER_URL : MCP 서버의 URL
• MCP_ADMIN_TOKEN : (선택 사항) 직접 액세스를 위한 관리자 토큰
• MCP_PROJECT_DIR : 프로젝트 디렉토리 경로

특허

MIT 라이센스

지역 사회

Discord 커뮤니티에 참여하여 Agent MCP에 대해 논의하고, 프로젝트를 공유하고, 도움을 받고, AI 도구를 활용하여 개발하는 다른 개발자들과 소통하세요. 저희는 다중 에이전트 시스템과 AI 협업을 통해 가능성의 한계를 넓히는 데 집중하는 성장하는 커뮤니티입니다.