MCP Integration Server

# MCP Integration Server - Salesforce & Atlassian A production-ready Model Context Protocol (MCP) server designed for AI agents to interact with Salesforce and Atlassian tools (Jira & Confluence), along with document management, analytics tracking, and general utilities. ## Features ### 🏢 Salesforce Tools - **salesforce_query**: Execute SOQL queries to retrieve records from any Salesforce object - **salesforce_get_record**: Get specific records by object type and ID - **salesforce_create_record**: Create new records (Accounts, Contacts, Opportunities, etc.) - **salesforce_update_record**: Update existing records - **salesforce_delete_record**: Delete records - **salesforce_search**: Search across multiple objects using SOSL ### 🎯 Jira Tools - **jira_get_issue**: Get full issue details including fields, comments, and attachments - **jira_create_issue**: Create tasks, bugs, stories, epics, and custom issue types - **jira_update_issue**: Update existing issues - **jira_search_issues**: Search issues using JQL (Jira Query Language) - **jira_add_comment**: Add comments to issues ### 📄 Confluence Tools - **confluence_get_page**: Get page content and metadata - **confluence_create_page**: Create new pages in any space - **confluence_update_page**: Update existing pages - **confluence_search**: Search pages and blog posts using CQL (Confluence Query Language) ### 📚 Document Management Tools - **create_document**: Create documents in the knowledge base - **search_documents**: Search documents by title, category, or tags - **update_document**: Update existing documents - **delete_document**: Delete documents by ID ### 📊 Analytics Tools - **track_event**: Track custom analytics events (page views, clicks, API calls) - **get_analytics_report**: Generate reports for specific event types or time ranges - **get_api_logs_report**: Generate API usage reports with success rates and performance metrics ### 🛠️ Utility Tools - **calculate**: Perform mathematical calculations - **format_date**: Format dates and calculate relative times - **generate_uuid**: Generate random UUIDs - **hash_string**: Generate SHA-256 or SHA-1 hashes - **http_request**: Make HTTP requests to external APIs ### 📖 Resources - **salesforce://{object}/{id}**: Access Salesforce records - **salesforce://summary**: Salesforce data overview - **jira://issue/{key}**: Access Jira issues - **confluence://page/{id}**: Access Confluence pages - **atlassian://summary**: Overview of Jira and Confluence data - **document://{id}**: Access documents from knowledge base - **analytics://events/summary**: Analytics events overview - **analytics://api-logs/summary**: API calls and performance overview ## Setup ### 1. Configure Environment Variables Copy the `.env.example` file to `.env` and fill in your credentials: ```bash cp .env.example .env ``` #### Salesforce Configuration 1. Log in to your Salesforce account 2. Get your instance URL (e.g., `https://your-domain.my.salesforce.com`) 3. Generate an access token using one of these methods: - **OAuth 2.0 Flow**: Create a Connected App and use OAuth to get an access token - **Session ID**: Use your session ID from a logged-in session (temporary) - **JWT Bearer Flow**: Set up JWT-based authentication (recommended for production) Documentation: https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/intro_oauth_and_connected_apps.htm #### Jira & Confluence Configuration 1. Go to https://id.atlassian.com/manage-profile/security/api-tokens 2. Click "Create API token" 3. Copy the token and use it for both Jira and Confluence 4. Your URLs should be: - Jira: `https://your-domain.atlassian.net` - Confluence: `https://your-domain.atlassian.net/wiki` (or just the base URL) ### 2. Set Up Database Schema Run this SQL migration in your Supabase SQL editor: ```sql -- Create documents table CREATE TABLE IF NOT EXISTS documents ( id uuid PRIMARY KEY DEFAULT gen_random_uuid(), title text NOT NULL, content text NOT NULL, category text DEFAULT 'general', tags text[] DEFAULT '{}', metadata jsonb DEFAULT '{}', created_at timestamptz DEFAULT now(), updated_at timestamptz DEFAULT now(), created_by uuid REFERENCES auth.users(id) ); -- Create analytics_events table CREATE TABLE IF NOT EXISTS analytics_events ( id uuid PRIMARY KEY DEFAULT gen_random_uuid(), event_type text NOT NULL, event_data jsonb DEFAULT '{}', user_id uuid REFERENCES auth.users(id), session_id text NOT NULL, timestamp timestamptz DEFAULT now(), metadata jsonb DEFAULT '{}' ); -- Create api_logs table CREATE TABLE IF NOT EXISTS api_logs ( id uuid PRIMARY KEY DEFAULT gen_random_uuid(), api_name text NOT NULL, endpoint text NOT NULL, request_data jsonb DEFAULT '{}', response_status integer, response_time_ms integer, success boolean DEFAULT false, error_message text, created_at timestamptz DEFAULT now(), user_id uuid REFERENCES auth.users(id) ); -- Create indexes CREATE INDEX IF NOT EXISTS idx_documents_category ON documents(category); CREATE INDEX IF NOT EXISTS idx_documents_tags ON documents USING GIN(tags); CREATE INDEX IF NOT EXISTS idx_analytics_event_type ON analytics_events(event_type); CREATE INDEX IF NOT EXISTS idx_analytics_timestamp ON analytics_events(timestamp DESC); CREATE INDEX IF NOT EXISTS idx_api_logs_api_name ON api_logs(api_name); -- Enable Row Level Security ALTER TABLE documents ENABLE ROW LEVEL SECURITY; ALTER TABLE analytics_events ENABLE ROW LEVEL SECURITY; ALTER TABLE api_logs ENABLE ROW LEVEL SECURITY; -- Documents policies CREATE POLICY "Anyone can read documents" ON documents FOR SELECT USING (true); CREATE POLICY "Authenticated users can insert documents" ON documents FOR INSERT TO authenticated WITH CHECK (auth.uid() = created_by); -- Analytics policies (service role access) CREATE POLICY "Service role can manage analytics" ON analytics_events FOR ALL TO service_role USING (true) WITH CHECK (true); CREATE POLICY "Service role can manage api logs" ON api_logs FOR ALL TO service_role USING (true) WITH CHECK (true); ``` ### 3. Build the MCP Server ```bash npm install npm run build ``` ### 4. Run the MCP Server ```bash npm run mcp:server ``` ## Integration Examples ### AI Agent Use Cases #### 1. Sales Pipeline Management ```typescript // Query all open opportunities { name: "salesforce_query", arguments: { query: "SELECT Id, Name, StageName, Amount, CloseDate FROM Opportunity WHERE StageName != 'Closed Won' AND StageName != 'Closed Lost' ORDER BY CloseDate" } } // Create a new lead from a conversation { name: "salesforce_create_record", arguments: { objectType: "Lead", fields: { FirstName: "John", LastName: "Doe", Company: "Acme Corp", Email: "john@acme.com", Status: "New", LeadSource: "AI Agent" } } } ``` #### 2. Customer Support Workflow ```typescript // Search for customer issues { name: "jira_search_issues", arguments: { jql: "project = SUPPORT AND status = 'In Progress' AND assignee = currentUser()", maxResults: 20 } } // Create a bug ticket { name: "jira_create_issue", arguments: { projectKey: "SUPPORT", issueType: "Bug", summary: "Customer reports login issue", description: "Customer cannot log in after password reset", priority: "High", labels: ["customer-support", "login"] } } // Add update comment { name: "jira_add_comment", arguments: { issueKey: "SUPPORT-123", comment: "Verified the issue. Root cause identified. Working on fix." } } ``` #### 3. Knowledge Management ```typescript // Search Confluence for documentation { name: "confluence_search", arguments: { cql: "type=page AND space=DOCS AND text~\"api authentication\"", limit: 10 } } // Create documentation page { name: "confluence_create_page", arguments: { spaceKey: "DOCS", title: "API Integration Guide", content: "<h1>API Integration</h1><p>This guide covers...</p>" } } // Store document in knowledge base { name: "create_document", arguments: { title: "Salesforce API Best Practices", content: "Full content here...", category: "technical-docs", tags: ["salesforce", "api", "best-practices"] } } ``` #### 4. Data Sync & Reporting ```typescript // Get Salesforce account and create Jira project { name: "salesforce_get_record", arguments: { objectType: "Account", recordId: "001..." } } // Then use the data to create corresponding Jira issues // Generate analytics report { name: "get_api_logs_report", arguments: { start_date: "2025-09-01T00:00:00Z", end_date: "2025-09-30T23:59:59Z" } } ``` ## Claude Desktop Integration Add this to your Claude Desktop configuration: **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "salesforce-atlassian": { "command": "node", "args": ["/path/to/your/project/mcp-server/dist/index.js"], "env": { "VITE_SUPABASE_URL": "your_supabase_url", "VITE_SUPABASE_ANON_KEY": "your_supabase_anon_key", "SALESFORCE_INSTANCE_URL": "your_salesforce_instance_url", "SALESFORCE_ACCESS_TOKEN": "your_salesforce_access_token", "JIRA_URL": "your_jira_url", "JIRA_EMAIL": "your_jira_email", "JIRA_API_TOKEN": "your_jira_api_token", "CONFLUENCE_URL": "your_confluence_url", "CONFLUENCE_EMAIL": "your_confluence_email", "CONFLUENCE_API_TOKEN": "your_confluence_api_token" } } } } ``` ## Using with Custom AI Agents ### Example: MCP Client in TypeScript ```typescript import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"; const transport = new StdioClientTransport({ command: "node", args: ["./mcp-server/dist/index.js"], }); const client = new Client({ name: "my-ai-agent", version: "1.0.0", }, { capabilities: {} }); await client.connect(transport); // List available tools const tools = await client.listTools(); console.log("Available tools:", tools.tools.map(t => t.name)); // Call Salesforce tool const accounts = await client.callTool({ name: "salesforce_query", arguments: { query: "SELECT Id, Name FROM Account LIMIT 5" } }); // Call Jira tool const issues = await client.callTool({ name: "jira_search_issues", arguments: { jql: "project = PROJ AND status = Open", maxResults: 10 } }); // Access resources const resources = await client.listResources(); // Read Salesforce summary const summary = await client.readResource({ uri: "salesforce://summary" }); ``` ## Architecture ``` mcp-server/ ├── index.ts # Main server entry point ├── types.ts # TypeScript type definitions ├── tools/ # Tool implementations │ ├── salesforce.ts # Salesforce CRUD and query tools │ ├── atlassian.ts # Jira & Confluence tools │ ├── documents.ts # Document management tools │ ├── analytics.ts # Analytics tracking tools │ └── utilities.ts # General utility tools └── resources/ # Resource providers ├── salesforce.ts # Salesforce data resources ├── atlassian.ts # Jira & Confluence resources ├── documents.ts # Document resources └── analytics.ts # Analytics resources ``` ## Best Practices for AI Agents ### 1. Authentication & Security - Store credentials securely in environment variables - Use OAuth refresh tokens for Salesforce in production - Rotate API tokens regularly - Never log sensitive data ### 2. Rate Limiting - Salesforce: 15,000 API calls per 24 hours (varies by license) - Jira/Confluence: Rate limits vary by plan (typically 10-100 requests/second) - Implement exponential backoff for retries ### 3. Data Consistency - Use transactions when possible - Implement idempotency for create operations - Handle concurrent updates carefully - Log all API calls for audit trails ### 4. Performance - Use SOQL/JQL filters to minimize data transfer - Cache frequently accessed data - Batch operations when possible - Monitor API response times via analytics ### 5. Error Handling - All tools include comprehensive error handling - Check API logs for debugging: `get_api_logs_report` - Implement retry logic for transient failures - Provide clear error messages to users ## Troubleshooting ### Salesforce Connection Issues - Verify instance URL is correct (no trailing slash) - Ensure access token is valid and not expired - Check user permissions in Salesforce - Review API version compatibility (currently using v59.0) ### Jira/Confluence Connection Issues - Verify URL format (e.g., `https://domain.atlassian.net`) - Confirm API token is valid - Check email matches the Atlassian account - Ensure user has appropriate permissions ### Common Errors **"Salesforce credentials not configured"** - Check `.env` file has SALESFORCE_INSTANCE_URL and SALESFORCE_ACCESS_TOKEN **"Jira credentials not configured"** - Check `.env` file has JIRA_URL, JIRA_EMAIL, and JIRA_API_TOKEN **"Unable to connect to Salesforce/Jira"** - Test credentials manually with curl or Postman - Check network connectivity and firewall rules - Verify API endpoints are accessible ## Support Resources - **Salesforce REST API**: https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/ - **Jira REST API**: https://developer.atlassian.com/cloud/jira/platform/rest/v3/ - **Confluence REST API**: https://developer.atlassian.com/cloud/confluence/rest/v1/ - **MCP SDK**: https://github.com/modelcontextprotocol/sdk - **Supabase**: https://supabase.com/docs ## License MIT