Agent MCP

에이전트 MCP

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

빠른 시작 가이드

참고 : 위의 스크린샷에 표시된 것처럼 동일한 코드베이스에서 여러 채팅 창을 실행하려면 MultipleCursor를 사용하는 것이 좋습니다.

1. 환경 설정

• 저장소를 복제하고 .env.example 을 .env 로 복사합니다.
• OpenAI API 키를 .env 에 추가하세요
• uv venv && uv pip install -e .

2. MCP 서버 시작

지엑스피1

중요 : 서버가 시작되면 프로젝트의 .agent 폴더에 데이터베이스가 생성됩니다. 관리자 토큰은 이 데이터베이스에 저장됩니다. 토큰을 찾는 방법은 다음과 같습니다.

1. 코드 편집기에 SQLite 뷰어 확장 프로그램을 설치하세요
2. /path/to/your/project/.agent/mcp_state.db 에서 데이터베이스를 엽니다.
3. 관리자 토큰에 대한 project_context 테이블을 확인하세요.

3. 메인 컨텍스트 문서(MCD) 생성

• 프로젝트에 아키텍처, API 경로, 데이터 모델 등을 포함하는 자세한 MCD.md 파일을 만듭니다.
• 이는 단일 파일 또는 여러 파일(복잡한 프로젝트의 경우)일 수 있습니다.
• 템플릿은 MCD-EXAMPLE 폴더를 참조하세요.

4. 관리 에이전트 실행

1. 프로젝트 폴더에서 AI 코딩 어시스턴트(Claude Code, Cursor 등)를 엽니다.
2. 2단계에서 찾은 관리자 토큰을 복사하세요
3. AI에게 "[your-token] 토큰을 사용하여 관리자 에이전트로 초기화"를 요청합니다.
4. 관리자 에이전트에게 다음을 사용하여 프로젝트 컨텍스트에 MCD를 추가하도록 요청하세요.
   Please add the MCD.md file to the project context. Don't summarize it.

5. 관리자를 통해 작업자 에이전트 생성 및 관리

1. 관리자 에이전트에게 작업자 에이전트를 생성하도록 요청하세요.
   Create a worker agent with ID "frontend-worker" to implement the login page.
2. AI 어시스턴트에서 새 창/세션을 엽니다(동일한 코드베이스)
3. 다음 프롬프트로 작업자를 초기화합니다.
   You are [worker-id] agent, your Admin Token: "[admin-token]" Look at your tasks and ask the project RAG agent at least 5-7 questions to understand what you need to do. I want you to critically think when asking a question, then criticize yourself before asking that question. How you criticize yourself is by proposing an idea, criticizing it, and based on that criticism you pull through with that idea. AUTO --worker --memory
4. 근로자는 자동으로 할당된 작업을 찾아 작업을 시작합니다.

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

특징

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

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

비디오 튜토리얼 보기: 에이전트 MCP에 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. 관리자 에이전트 설정 : 토큰과 docs/INSTRUCTIONS.md를 사용하여 관리자 에이전트를 초기화합니다.
4. 작업자 생성 : 관리자는 프로젝트의 다양한 측면에 대한 전문 작업자를 생성합니다.
5. 작업 할당 : 관리자는 MCD를 개별 작업으로 분할하고 작업자에게 할당합니다.
6. 병렬 개발 : 작업자는 MCP를 통해 컨텍스트를 공유하면서 작업을 실행합니다.
7. 컨텍스트 보존 : 모든 에이전트는 자신의 지식을 중앙 데이터베이스에 저장합니다.

개발 루프

아키텍처 개요

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

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

에이전트 설정 및 운영

1. MCP 서버 시작

옵션:

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

2. MCP 토큰 이해

MCP 시스템은 인증을 위해 두 가지 유형의 토큰을 사용합니다.

관리자 토큰 :

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

작업자 토큰 :

1. 관리자 에이전트가 작업자 에이전트를 생성하면 특정 작업자 토큰이 생성됩니다.
2. 관리자 에이전트는 작업자를 생성하라는 요청을 받으면 이 작업자 토큰을 제공합니다.
3. 각 작업자는 특정 권한이 있는 고유한 토큰을 가지고 있습니다.
4. 작업자 토큰은 .agent/mcp_state.db 데이터베이스에도 저장됩니다.

중요 : 워커 에이전트에 관리자 토큰을 사용하지 마십시오. 관리자 에이전트가 워커를 생성할 때 제공하는 특정 워커 토큰을 항상 사용하십시오.

3. 에이전트 워크플로(중요)

참고 : 모든 에이전트는 AI 비서와의 채팅을 통해 생성되고 관리됩니다. 에이전트를 생성하는 데 명령줄 도구는 사용하지 않습니다.

MCP 서버 - 명령으로 시작하는 유일한 구성 요소입니다.

관리자 에이전트 - AI 비서에게 다음과 같이 말하여 생성합니다.

작업자 에이전트 - 다음을 사용하여 관리 에이전트를 통해 생성:

1. 관리자 에이전트에게 "로그인 페이지를 구현하기 위해 ID가 'frontend-worker'인 작업자 에이전트를 생성하세요"라고 알려주세요.
2. 관리자는 이 에이전트에 대해 특정 작업자 토큰을 제공합니다.
3. 새로운 AI 어시스턴트 창/세션을 엽니다
4. 아래 섹션 4의 작업자 토큰과 작업자 프롬프트로 초기화합니다.

대시보드 ( http://localhost:8080 ):

• 이것은 시각화를 위한 것일 뿐입니다. 여기서는 에이전트를 생성하지 않습니다.
• 모든 실제 작업은 AI 지원 채팅 창을 통해 이루어집니다.
• 대시보드는 에이전트와 작업 간의 관계를 보여줍니다.

4. 워커 에이전트 초기화(복사/붙여넣기)

관리자 에이전트가 작업자를 생성한 후 새 AI 어시스턴트 창을 열고 다음과 같은 프롬프트로 작업자를 초기화합니다.

다음 두 가지를 바꿔보세요.

1. [agent_id] 관리자에게 생성하도록 지시한 작업자 ID(예: "frontend-worker")로 바꾸세요.
2. your_worker_token_here 관리자 에이전트가 이 작업자를 생성할 때 제공한 특정 작업자 토큰으로 바꾸세요(관리자 토큰이 아님)

초기화 후 작업자는 다음을 수행합니다.

1. 해당 ID에 할당된 작업을 확인하세요
2. RAG 시스템에 프로젝트 컨텍스트에 대해 문의하세요.
3. 자율적으로 작업을 시작합니다.
4. 공유 메모리 시스템에 구현 세부 정보 저장

최상의 결과를 얻으려면 docs/INSTRUCTIONS.md 의 내용도 복사하여 AUTO 명령 앞에 붙여 넣으세요.

대시보드 및 터미널 UI

대시보드(시각화)

http://localhost:8080 에서 대시보드에 액세스하여 다중 에이전트 시스템에서 무슨 일이 일어나고 있는지 시각화하세요.

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

중요: 대시보드는 시각화용으로만 사용되며, 여기에서는 에이전트를 생성하거나 관리할 수 없습니다. 모든 에이전트 생성 및 작업 할당은 AI 비서 채팅을 통해 이루어집니다.

다중 에이전트 세션: 시각적 가이드

복잡한 프로젝트의 경우 여러 개의 채팅 세션을 동시에 열 수 있습니다.

작동 방식:

1. 관리자 에이전트를 위한 하나의 창/세션
2. 각 작업자 에이전트에 대해 별도의 창/세션
3. 관리자는 관리자 토큰을 사용하고, 작업자는 특정 작업자 토큰을 사용합니다.
4. 각 작업자는 고유한 에이전트 ID와 토큰을 갖습니다.

3명의 에이전트를 사용한 설정 예시:

Claude Code, RooCode 또는 MultipleCursor를 사용하면 동일한 코드베이스에서 작업하는 여러 창/세션을 관리할 수 있습니다.

전체 예제 워크플로

Agent MCP를 처음부터 끝까지 사용하는 방법에 대한 단계별 예는 다음과 같습니다.

1단계: 프로젝트 만들기

2단계: Agent MCP 설치

3단계: MCD 만들기

4단계: MCP 서버 시작

5단계: 관리자 토큰 찾기

1. 코드 편집기에 SQLite Viewer를 설치하세요
2. .agent/mcp_state.db 엽니다.
3. project_context 테이블에서 토큰을 찾으세요

6단계: 관리 에이전트 초기화

1. AI 비서(Claude Code, Cursor 등)를 엽니다.
2. 말해 보세요:

7단계: 작업자 에이전트 만들기

1. 관리자 에이전트에게 알려주세요:

2. 관리자 에이전트는 이 새로운 에이전트에 대한 작업자 토큰을 제공합니다.

8단계: Worker Agent 초기화

1. 새로운 AI 어시스턴트 창 열기
2. 말해 보세요:

이제 작업자는 자동으로 할당된 작업을 시작합니다!

토큰 시스템 및 리소스 관리

토큰 이해

토큰은 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 프로젝트 및 지식 기반(중앙 메모리 시스템)

위의 튜토리얼을 시청하세요: MCD를 중앙 메모리 시스템에 추가하는 방법을 정확히 알아보세요.

메모리 시스템의 작동 방식

1. MCP 서버는 모든 프로젝트 컨텍스트에 대한 중앙 데이터베이스를 유지합니다.
2. 서버를 시작하면 프로젝트 디렉토리에 .agent 폴더가 생성됩니다.
3. 관리자 에이전트는 초기화할 때 이 데이터베이스에 MCD를 추가합니다.
4. 작업자 에이전트는 이 데이터베이스를 자동으로 쿼리하여 작업을 파악합니다.
5. 모든 구현 세부 사항은 다른 에이전트가 액세스할 수 있도록 이 데이터베이스에 다시 저장됩니다.

프로젝트 RAG 설정

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

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

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

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

지역 사회

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