Agentforce MCP 서버

이 MCP 서버는 Salesforce Agentforce API와 상호 작용하는 도구를 제공합니다. Agentforce 에이전트와의 인증, 세션 생성 및 메시지 교환이 가능합니다.

복제 후 시작하기

이 저장소를 방금 복제했다면 대화형 설정 스크립트를 사용하여 서버를 빠르게 구성하고 실행할 수 있습니다.

지엑스피1

설정 스크립트는 다음을 수행합니다.

1. Python 버전을 확인하세요
2. 필수 종속성 설치
3. Salesforce 자격 증명을 입력하는 방법을 안내합니다.
4. Salesforce에 대한 연결을 테스트하세요
5. 서버 시작 제안
6. Claude Desktop 구성에 대한 지침을 제공합니다.

또는 다음 수동 단계를 따를 수 있습니다.

1. 종속성 설치 :
   pip install -r requirements.txt
2. 환경 변수를 설정하세요 :
   cp .env.example .env
3. Salesforce 자격 증명을 수집하세요 :
   • SALESFORCE_ORG_ID : 18자리 Salesforce 조직 ID
   • SALESFORCE_AGENT_ID : Agentforce 에이전트의 18자 에이전트 ID
   • SALESFORCE_CLIENT_ID : 연결된 앱의 소비자 키
   • SALESFORCE_CLIENT_SECRET : 연결된 앱의 소비자 비밀번호
   • SALESFORCE_SERVER_URL : https:// 접두사가 없는 Salesforce 내 도메인 URL
4. 수집된 자격 증명으로 .env 파일을 편집합니다 .
   SALESFORCE_ORG_ID="00D5f000000J2PKEA0" SALESFORCE_AGENT_ID="0XxHn000000x9F1KAI" SALESFORCE_CLIENT_ID="3MVG9OGq41FnYVsFgnaG0AzJDWnoy37Bb18e0R.GgDJu2qB9sqppVl7ehWmJhGvPSLrrA0cBNhDJdsbZXnv52" SALESFORCE_CLIENT_SECRET="210117AC36E9E4C8AFCA02FF062B8A677BACBFFB71D2BB1162D60D316382FADE" SALESFORCE_SERVER_URL="example.my.salesforce.com"
   (참고: 이는 가상의 예시 값입니다. 실제 자격 증명으로 바꾸세요.)
5. 서버 스크립트를 실행 가능하게 만들기 :
   chmod +x agentforce_mcp_server.py
6. 서버를 실행합니다 :
   python agentforce_mcp_server.py

Salesforce 자격 증명을 찾는 방법에 대한 자세한 지침은 아래의 Salesforce 설정 섹션을 참조하세요.

설정

1. Python 3.10 이상이 설치되어 있는지 확인하세요.
2. 필요한 종속성을 설치하세요:
   pip install -r requirements.txt
3. 서버 스크립트를 실행 가능하게 만듭니다.
   chmod +x agentforce_mcp_server.py

구성

서버는 구성에 환경 변수를 사용합니다. 환경 변수는 .env 파일에서 로드됩니다.

1. 예제 환경 파일을 복사하여 나만의 환경 파일을 만드세요.
   cp .env.example .env
2. .env 파일을 편집하여 값을 입력하세요.
   SALESFORCE_ORG_ID="your_org_id_here" SALESFORCE_AGENT_ID="your_agent_id_here" # The 18-character Agent ID you found in Salesforce SALESFORCE_CLIENT_ID="your_client_id_here" # The Consumer Key from your Connected App SALESFORCE_CLIENT_SECRET="your_client_secret_here" # The Consumer Secret from your Connected App SALESFORCE_SERVER_URL="your_server_url_here" # Your My Domain URL (e.g., example.my.salesforce.com)

Salesforce 구성

Agentforce API를 사용하려면 다음이 필요합니다.

1. Salesforce 조직에서 연결된 앱 만들기
2. Agentforce 에이전트 ID 찾기
3. Salesforce 내 도메인 URL을 기록하세요.

이러한 단계에 대한 자세한 지침은 아래의 Salesforce 설정 섹션을 참조하세요.

서버 실행

다음을 사용하여 서버를 실행합니다.

사용 가능한 도구

MCP 서버는 다음 도구를 제공합니다.

1. authenticate

클라이언트 이메일을 사용하여 Agentforce API로 인증합니다.

매개변수:

• client_email : 인증을 위한 클라이언트의 이메일

2. create_agent_session

구성된 Agentforce 에이전트로 세션을 생성합니다.

매개변수:

• client_email : 인증된 클라이언트의 이메일

3. send_message_to_agent

Agentforce 에이전트에 메시지를 보내고 응답을 반환합니다.

매개변수:

• client_email : 인증된 클라이언트의 이메일
• message : 상담원에게 보낼 메시지

4. get_session_status

인증 상태, 세션 ID, 시퀀스 ID를 포함하여 현재 세션의 상태를 가져옵니다.

매개변수:

• client_email : 인증된 클라이언트의 이메일

5. complete_agentforce_conversation

인증, 세션 생성, 메시지 전송 등 전체 흐름을 처리하는 편리한 방법입니다.

매개변수:

• client_email : 인증을 위한 클라이언트의 이메일
• user_query : 에이전트에게 보낼 메시지

Claude와 함께 데스크톱 사용

Claude for Desktop과 함께 이 서버를 사용하려면 claude_desktop_config.json 파일을 업데이트하세요.

경로를 컴퓨터의 서버 스크립트에 대한 절대 경로로 바꾸세요.

플랫폼별 경로 위치

맥OS

• 구성 파일: ~/Library/Application Support/Claude/claude_desktop_config.json
• 경로 예: /Users/yourusername/Projects/agentforce-mcp-server/agentforce_mcp_server.py

윈도우

• 구성 파일: %APPDATA%\Claude\claude_desktop_config.json
• 경로 예: C:\Users\yourusername\Projects\agentforce-mcp-server\agentforce_mcp_server.py

Salesforce 설정

연결된 앱 만들기

Agentforce API를 사용하려면 Salesforce 조직에서 연결된 앱을 만들어야 합니다.

1. 관리자로 Salesforce 조직에 로그인하세요.
2. 설정 으로 이동
3. 빠른 찾기 상자에서 "앱 관리자"를 검색하여 클릭합니다.
4. 새로 연결된 앱 버튼을 클릭하세요
5. 기본 정보를 입력하세요:
   • 연결된 앱 이름 : Agentforce MCP 통합(또는 원하는 이름)
   • API 이름 : Agentforce_MCP_Integration(자동으로 채워짐)
   • 연락처 이메일 : 귀하의 이메일 주소
6. OAuth 설정 활성화를 체크하세요
7. 콜백 URL을 https://localhost/oauth/callback 으로 설정합니다(사용되지 않지만 필수입니다)
8. 선택한 OAuth 범위 에서 다음을 추가합니다.
   • API(api)를 통해 사용자 데이터 관리
   • 언제든지 요청 수행(refresh_token, offline_access)
9. 저장을 클릭하세요
10. 저장 후 연결된 앱 세부 정보 페이지로 리디렉션됩니다.
11. 소비자 키 (클라이언트 ID)를 기록하고 소비자 비밀번호 옆에 있는 '클릭하여 공개'를 클릭하여 클라이언트 비밀번호를 얻으세요.

에이전트 ID 찾기

Agentforce 에이전트 ID를 찾으려면:

1. Salesforce 조직에 로그인하세요
2. Einstein Agent Builder 로 이동
3. 사용할 에이전트를 선택하세요
4. 브라우저에서 URL을 확인하세요. 다음 형식의 에이전트 ID가 포함되어 있습니다: https://your-salesforce-instance.lightning.force.com/lightning/r/Agent__c/0XxXXXXXXXXXXXXX/view
5. Agent ID는 URL에 있는 18자리 ID( 0XxXXXXXXXXXXXXX )입니다.

Salesforce 내 도메인 URL 찾기

Salesforce 내 도메인 URL을 찾으려면:

1. Salesforce 조직에 로그인하세요
2. 설정 으로 이동
3. 빠른 찾기 상자에서 "내 도메인"을 검색하고 클릭합니다.
4. 귀하의 도메인은 DOMAIN-NAME.my.salesforce.com 형식으로 표시됩니다.
5. .env 파일에서 "https://" 접두사 없이 이 URL을 사용하세요.

조직 ID 찾기

Salesforce 조직 ID를 찾으려면:

1. Salesforce 조직에 로그인하세요
2. 설정 으로 이동
3. 빠른 찾기 상자에서 "회사 정보"를 검색하고 클릭하십시오.
4. "조직 ID" 필드를 찾으세요. 이는 Salesforce 조직 ID입니다.
5. 15자 또는 18자의 영숫자 문자열이 됩니다.

노트

• 서버는 메시지 교환을 위한 시퀀스 ID를 자동으로 관리합니다.
• 각 클라이언트 이메일에 대한 인증 및 세션 상태가 유지됩니다.
• 모든 API 상호 작용은 디버깅 목적으로 기록됩니다.

문제 해결

문제가 발생하는 경우:

1. 인증 실패 : 연결된 앱 설정을 확인하고 클라이언트 ID와 비밀번호가 올바른지 확인하세요.
2. 세션 생성 오류 : 에이전트 ID를 확인하고 18자 버전인지 확인하세요.
3. 연결 문제 : Salesforce 내 도메인 URL이 올바른지 확인하세요("https://" 접두사 없음)
4. 권한 오류 : 연결된 앱에 적절한 OAuth 범위가 활성화되어 있는지 확인하세요.

설정 테스트

포함된 테스트 스크립트를 사용하여 설정을 테스트할 수 있습니다.

이렇게 하면 Agentforce 에이전트와 인증, 세션 생성, 메시지 교환이 시도됩니다.

기여 및 GitHub Push

이 저장소에는 GitHub에 변경 사항을 푸시하는 과정을 단순화하는 유용한 스크립트가 포함되어 있습니다.

github_push.sh 스크립트는 다음을 수행합니다.

1. 시스템에 git이 설치되어 있는지 확인하세요
2. .env 와 같은 민감한 파일이 푸시되지 않도록 확인하세요(해당 파일은 .gitignore 에 있습니다)
3. GitHub 저장소 URL을 입력하라는 메시지가 표시됩니다.
4. 필요한 경우 git 저장소를 초기화하거나 원격 URL을 업데이트합니다.
5. 모든 파일을 추가하고 검토를 위해 표시합니다.
6. 설명적인 메시지로 변경 사항을 커밋합니다.
7. 변경 사항을 GitHub에 푸시하세요

이를 통해 민감한 정보가 안전하게 보호되는 동시에 사용자 정의 내용을 쉽게 공유하거나 프로젝트에 다시 기여할 수 있습니다.