Servidor MCP de Agentforce

Este servidor MCP proporciona herramientas para interactuar con la API de Salesforce Agentforce. Permite la autenticación, la creación de sesiones y el intercambio de mensajes con agentes de Agentforce.

Primeros pasos después de la clonación

Si acaba de clonar este repositorio, puede utilizar el script de configuración interactivo para configurar y ejecutar rápidamente el servidor:

El script de configuración hará lo siguiente:

1. Comprueba tu versión de Python
2. Instalar las dependencias necesarias
3. Le guiaremos en el proceso de ingreso de sus credenciales de Salesforce
4. Pruebe su conexión a Salesforce
5. Oferta para iniciar el servidor
6. Proporcionar instrucciones para configurar Claude Desktop

Alternativamente, puede seguir estos pasos manuales:

1. Instalar dependencias :
   pip install -r requirements.txt
2. Configure sus variables de entorno :
   cp .env.example .env
3. Recopile sus credenciales de Salesforce :
   • SALESFORCE_ORG_ID : Su ID de organización de Salesforce de 18 caracteres
   • SALESFORCE_AGENT_ID : El ID de agente de 18 caracteres de su agente de Agentforce
   • SALESFORCE_CLIENT_ID : La clave del consumidor de su aplicación conectada
   • SALESFORCE_CLIENT_SECRET : El secreto del consumidor desde tu aplicación conectada
   • SALESFORCE_SERVER_URL : Su URL de Mi Dominio de Salesforce sin el prefijo https://
4. Edite su archivo .env con las credenciales recopiladas:
   SALESFORCE_ORG_ID="00D5f000000J2PKEA0" SALESFORCE_AGENT_ID="0XxHn000000x9F1KAI" SALESFORCE_CLIENT_ID="3MVG9OGq41FnYVsFgnaG0AzJDWnoy37Bb18e0R.GgDJu2qB9sqppVl7ehWmJhGvPSLrrA0cBNhDJdsbZXnv52" SALESFORCE_CLIENT_SECRET="210117AC36E9E4C8AFCA02FF062B8A677BACBFFB71D2BB1162D60D316382FADE" SALESFORCE_SERVER_URL="example.my.salesforce.com"
   (Nota: Estos son valores de ejemplo ficticios. Reemplácelos con sus credenciales reales).
5. Hacer que el script del servidor sea ejecutable :
   chmod +x agentforce_mcp_server.py
6. Ejecutar el servidor :
   python agentforce_mcp_server.py

Para obtener instrucciones detalladas sobre cómo encontrar sus credenciales de Salesforce, consulte la sección Configuración de Salesforce a continuación.

Configuración

1. Asegúrese de tener instalado Python 3.10 o superior.
2. Instale las dependencias necesarias:
   pip install -r requirements.txt
3. Hacer que el script del servidor sea ejecutable:
   chmod +x agentforce_mcp_server.py

Configuración

El servidor utiliza variables de entorno para la configuración. Estas se cargan desde el archivo .env .

1. Copie el archivo de entorno de ejemplo para crear el suyo propio:
   cp .env.example .env
2. Edite el archivo .env y complete sus valores:
   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)

Configuración de Salesforce

Para utilizar la API de Agentforce, debe:

1. Cree una aplicación conectada en su organización de Salesforce
2. Encuentre su ID de agente de Agentforce
3. Anote la URL de su dominio de Salesforce

Para obtener instrucciones detalladas sobre estos pasos, consulte la sección Configuración de Salesforce a continuación.

Ejecución del servidor

Ejecute el servidor usando:

Herramientas disponibles

El servidor MCP expone las siguientes herramientas:

1. authenticate

Se autentica con la API de Agentforce mediante un correo electrónico de cliente.

Parámetros:

• client_email : Correo electrónico del cliente para autenticación

2. create_agent_session

Crea una sesión con el agente Agentforce configurado.

Parámetros:

• client_email : Correo electrónico del cliente autenticado

3. send_message_to_agent

Envía un mensaje al agente de Agentforce y devuelve la respuesta.

Parámetros:

• client_email : Correo electrónico del cliente autenticado
• message : Mensaje para enviar al agente

4. get_session_status

Obtiene el estado de la sesión actual, incluido el estado de autenticación, el ID de sesión y el ID de secuencia.

Parámetros:

• client_email : Correo electrónico del cliente autenticado

5. complete_agentforce_conversation

Método de conveniencia que maneja el flujo completo: autenticación, creación de sesión y envío de mensajes.

Parámetros:

• client_email : Correo electrónico del cliente para autenticación
• user_query : Mensaje a enviar al agente

Uso con Claude para escritorio

Para utilizar este servidor con Claude for Desktop, actualice su archivo claude_desktop_config.json :

Reemplace la ruta con la ruta absoluta al script del servidor en su máquina.

Ubicaciones de rutas por plataforma

macOS

• Archivo de configuración: ~/Library/Application Support/Claude/claude_desktop_config.json
• Ruta de ejemplo: /Users/yourusername/Projects/agentforce-mcp-server/agentforce_mcp_server.py

Ventanas

• Archivo de configuración: %APPDATA%\Claude\claude_desktop_config.json
• Ruta de ejemplo: C:\Users\yourusername\Projects\agentforce-mcp-server\agentforce_mcp_server.py

Configuración de Salesforce

Creación de una aplicación conectada

Para utilizar la API de Agentforce, debe crear una aplicación conectada en su organización de Salesforce:

1. Inicie sesión en su organización de Salesforce como administrador
2. Ir a Configuración
3. En el cuadro de Búsqueda rápida, busque "Administrador de aplicaciones" y haga clic en él.
4. Haga clic en el botón Nueva aplicación conectada
5. Complete la información básica:
   • Nombre de la aplicación conectada : Integración de Agentforce MCP (o cualquier nombre que prefiera)
   • Nombre de la API : Agentforce_MCP_Integration (se completará automáticamente)
   • Correo electrónico de contacto : Su dirección de correo electrónico
6. Marque la casilla Habilitar configuración de OAuth
7. Establezca la URL de devolución de llamada en https://localhost/oauth/callback (no se utiliza, pero es obligatorio)
8. En Ámbitos OAuth seleccionados , agregue:
   • Gestionar datos de usuarios a través de APIs (api)
   • Realizar solicitudes en cualquier momento (refresh_token, offline_access)
9. Haga clic en Guardar
10. Después de guardar, será redirigido a la página de detalles de la aplicación conectada.
11. Anote la clave del consumidor (esta es su ID de cliente) y haga clic en Hacer clic para revelar junto a Secreto del consumidor para obtener su secreto de cliente

Cómo encontrar su ID de agente

Para encontrar su ID de agente de Agentforce:

1. Inicie sesión en su organización de Salesforce
2. Vaya a Einstein Agent Builder
3. Seleccione el agente que desea utilizar
4. Mire la URL en su navegador: contendrá el ID del agente en el formato: https://your-salesforce-instance.lightning.force.com/lightning/r/Agent__c/0XxXXXXXXXXXXXXX/view
5. El ID del agente es ese ID de 18 caracteres ( 0XxXXXXXXXXXXXXX ) en la URL

Cómo encontrar la URL de mi dominio de Salesforce

Para encontrar la URL de Mi dominio de Salesforce:

1. Inicie sesión en su organización de Salesforce
2. Ir a Configuración
3. En el cuadro de Búsqueda rápida, busque "Mi dominio" y haga clic en él.
4. Verá su dominio en el formato DOMAIN-NAME.my.salesforce.com
5. Utilice esta URL sin el prefijo "https://" en su archivo .env

Cómo encontrar el ID de su organización

Para encontrar su ID de organización de Salesforce:

1. Inicie sesión en su organización de Salesforce
2. Ir a Configuración
3. En el cuadro de Búsqueda rápida, busque "Información de la empresa" y haga clic en él.
4. Busque el campo "ID de organización": este es su ID de organización de Salesforce
5. Será una cadena alfanumérica de 15 o 18 caracteres.

Notas

• El servidor administra automáticamente los identificadores de secuencia para los intercambios de mensajes
• La autenticación y el estado de la sesión se mantienen para cada correo electrónico del cliente.
• Todas las interacciones de la API se registran con fines de depuración.

Solución de problemas

Si encuentra problemas:

1. Errores de autenticación : Verifique la configuración de su aplicación conectada y asegúrese de que el ID del cliente y el secreto sean correctos
2. Errores de creación de sesión : Verifique su ID de agente y asegúrese de que sea la versión de 18 caracteres
3. Problemas de conexión : Verifique que la URL de su dominio de Salesforce sea correcta (sin el prefijo "https://")
4. Errores de permisos : asegúrese de que su aplicación conectada tenga habilitados los ámbitos OAuth adecuados

Probando la configuración

Puede probar su configuración utilizando el script de prueba incluido:

Esto intentará autenticarse, crear una sesión e intercambiar mensajes con su agente de Agentforce.

Contribución y GitHub Push

Este repositorio incluye un script útil que simplifica el proceso de enviar sus cambios a GitHub:

El script github_push.sh hará lo siguiente:

1. Comprueba si Git está instalado en tu sistema
2. Verifique que no se envíen archivos confidenciales como .env (están en .gitignore )
3. Le solicitará la URL de su repositorio de GitHub
4. Inicialice un repositorio git si es necesario o actualice la URL remota
5. Agregue todos los archivos y muéstrelos para su revisión
6. Confirme los cambios con un mensaje descriptivo
7. Envía los cambios a GitHub

Esto hace que sea más fácil compartir sus personalizaciones o contribuir al proyecto y al mismo tiempo garantizar que la información confidencial se mantenga segura.