Merge pull request #5171 from Ttian18/feat/tina/intercom-tool-4256

feat(tools): add Intercom tool integration (#4256)

Author: bryanadenhq

tools/src/aden_tools/credentials/__init__.py

@@ -40,6 +40,7 @@
 - discord.py: Discord bot credentials
 - github.py: GitHub API credentials
 - hubspot.py: HubSpot CRM credentials
+- intercom.py: Intercom customer messaging credentials
 - slack.py: Slack workspace credentials
 - google_analytics.py: Google Analytics credentials
 - google_maps.py: Google Maps Platform credentials
@@ -75,6 +76,7 @@
     validate_integration_wiring,
 )
 from .hubspot import HUBSPOT_CREDENTIALS
+from .intercom import INTERCOM_CREDENTIALS
 from .llm import LLM_CREDENTIALS
 from .news import NEWS_CREDENTIALS
 from .postgres import POSTGRES_CREDENTIALS
@@ -106,6 +108,7 @@
     **GOOGLE_DOCS_CREDENTIALS,
     **GOOGLE_MAPS_CREDENTIALS,
     **HUBSPOT_CREDENTIALS,
+    **INTERCOM_CREDENTIALS,
     **GOOGLE_CALENDAR_CREDENTIALS,
     **SLACK_CREDENTIALS,
     **SERPAPI_CREDENTIALS,
@@ -152,6 +155,7 @@
     "GOOGLE_DOCS_CREDENTIALS",
     "GOOGLE_MAPS_CREDENTIALS",
     "HUBSPOT_CREDENTIALS",
+    "INTERCOM_CREDENTIALS",
     "GOOGLE_CALENDAR_CREDENTIALS",
     "SLACK_CREDENTIALS",
     "APOLLO_CREDENTIALS",

tools/src/aden_tools/credentials/health_check.py

@@ -1058,6 +1058,16 @@ def _extract_identity(self, data: dict) -> dict[str, str]:
         return identity
 
 
+class IntercomHealthChecker(OAuthBearerHealthChecker):
+    """Health checker for Intercom access tokens."""
+
+    def __init__(self):
+        super().__init__(
+            endpoint="https://api.intercom.io/me",
+            service_name="Intercom",
+        )
+
+
 # Registry of health checkers
 HEALTH_CHECKERS: dict[str, CredentialHealthChecker] = {
     "discord": DiscordHealthChecker(),
@@ -1070,6 +1080,7 @@ def _extract_identity(self, data: dict) -> dict[str, str]:
     "google_maps": GoogleMapsHealthChecker(),
     "anthropic": AnthropicHealthChecker(),
     "github": GitHubHealthChecker(),
+    "intercom": IntercomHealthChecker(),
     "resend": ResendHealthChecker(),
     "stripe": StripeHealthChecker(),
     "exa_search": ExaSearchHealthChecker(),

tools/src/aden_tools/credentials/intercom.py

@@ -0,0 +1,49 @@
+"""
+Intercom tool credentials.
+
+Contains credentials for Intercom customer messaging integration.
+"""
+
+from .base import CredentialSpec
+
+INTERCOM_CREDENTIALS = {
+    "intercom": CredentialSpec(
+        env_var="INTERCOM_ACCESS_TOKEN",
+        tools=[
+            "intercom_search_conversations",
+            "intercom_get_conversation",
+            "intercom_get_contact",
+            "intercom_search_contacts",
+            "intercom_add_note",
+            "intercom_add_tag",
+            "intercom_assign_conversation",
+            "intercom_list_teams",
+        ],
+        required=True,
+        startup_required=False,
+        help_url=(
+            "https://developers.intercom.com/docs/build-an-integration/learn-more/authentication"
+        ),
+        description=(
+            "Intercom access token (Settings > Integrations"
+            " > Developer Hub > Your App > Authentication)"
+        ),
+        # Auth method support
+        aden_supported=False,
+        direct_api_key_supported=True,
+        api_key_instructions="""To get an Intercom access token:
+1. Go to https://app.intercom.com
+2. Navigate to Settings > Integrations > Developer Hub
+3. Click "New app" (or select an existing app)
+4. Go to the "Authentication" tab
+5. Copy the access token
+6. Required scopes: Read and write conversations, \
+Read contacts, Read and write tags, Read admins""",
+        # Health check configuration
+        health_check_endpoint="https://api.intercom.io/me",
+        health_check_method="GET",
+        # Credential store mapping
+        credential_id="intercom",
+        credential_key="access_token",
+    ),
+}

tools/src/aden_tools/tools/__init__.py

@@ -59,6 +59,7 @@
 from .google_maps_tool import register_tools as register_google_maps
 from .http_headers_scanner import register_tools as register_http_headers_scanner
 from .hubspot_tool import register_tools as register_hubspot
+from .intercom_tool import register_tools as register_intercom
 from .news_tool import register_tools as register_news
 from .pdf_read_tool import register_tools as register_pdf_read
 from .port_scanner import register_tools as register_port_scanner
@@ -115,6 +116,7 @@ def register_all_tools(
     # Gmail inbox management (read, trash, modify labels)
     register_gmail(mcp, credentials=credentials)
     register_hubspot(mcp, credentials=credentials)
+    register_intercom(mcp, credentials=credentials)
     register_apollo(mcp, credentials=credentials)
     register_bigquery(mcp, credentials=credentials)
     register_calcom(mcp, credentials=credentials)

tools/src/aden_tools/tools/intercom_tool/README.md

@@ -0,0 +1,99 @@
+# Intercom Tool
+
+Customer messaging, conversations, and support automation via the Intercom API (v2.11).
+
+## Setup
+
+### 1. Get an Access Token
+
+1. Log in to your [Intercom Developer Hub](https://app.intercom.com/a/apps/_/developer-hub)
+2. Create or select an app
+3. Go to **Authentication** and copy the access token
+4. Ensure the app has the required scopes for the tools you need (e.g., `Read and List conversations`, `Manage conversations`, `Read and Write contacts`)
+
+### 2. Configure the Token
+
+Set the environment variable:
+
+```bash
+export INTERCOM_ACCESS_TOKEN="your-access-token-here"
+```
+
+Or configure via the Hive credential store.
+
+## Tools (8 Total)
+
+### Conversations (2)
+
+| Tool | Description |
+|------|-------------|
+| `intercom_search_conversations` | Search conversations with filters (status, assignee, tag, date) |
+| `intercom_get_conversation` | Get full conversation details including message history |
+
+### Contacts (2)
+
+| Tool | Description |
+|------|-------------|
+| `intercom_get_contact` | Get a contact by ID or email |
+| `intercom_search_contacts` | Search contacts by email, name, or custom attributes |
+
+### Notes, Tags & Assignment (3)
+
+| Tool | Description |
+|------|-------------|
+| `intercom_add_note` | Add an internal note to a conversation |
+| `intercom_add_tag` | Add a tag to a conversation or contact |
+| `intercom_assign_conversation` | Assign a conversation to an admin or team |
+
+### Teams (1)
+
+| Tool | Description |
+|------|-------------|
+| `intercom_list_teams` | List available teams for conversation routing |
+
+## Usage Examples
+
+```python
+# Search open conversations
+intercom_search_conversations(status="open", limit=10)
+
+# Get full conversation details
+intercom_get_conversation(conversation_id="12345")
+
+# Find a contact by email
+intercom_get_contact(email="jane@example.com")
+
+# Add an internal note
+intercom_add_note(conversation_id="12345", body="Escalating to engineering")
+
+# Tag a conversation
+intercom_add_tag(name="VIP", conversation_id="12345")
+
+# Assign to a team
+intercom_assign_conversation(
+    conversation_id="12345",
+    assignee_id="67890",
+    assignee_type="team",
+    body="Routing to billing team"
+)
+
+# List available teams
+intercom_list_teams()
+```
+
+## Error Handling
+
+All tools return error dictionaries on failure:
+
+```python
+{"error": "Intercom credentials not configured", "help": "Set INTERCOM_ACCESS_TOKEN..."}
+{"error": "Invalid or expired Intercom access token"}
+{"error": "Insufficient permissions. Check your Intercom app scopes."}
+{"error": "Resource not found"}
+{"error": "Intercom rate limit exceeded. Try again later."}
+{"error": "Request timed out"}
+```
+
+## References
+
+- [Intercom API Documentation](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/)

tools/src/aden_tools/tools/intercom_tool/__init__.py

@@ -0,0 +1,9 @@
+"""
+Intercom Tool - Manage conversations, contacts, and tags via Intercom API v2.11.
+
+Supports access token authentication.
+"""
+
+from .intercom_tool import register_tools
+
+__all__ = ["register_tools"]