diff --git a/servers/asana/README.md b/servers/asana/README.md new file mode 100644 index 0000000..556b744 --- /dev/null +++ b/servers/asana/README.md @@ -0,0 +1,137 @@ +# Asana MCP Server + +A comprehensive Model Context Protocol (MCP) server for Asana, providing AI assistants with full access to Asana's project management capabilities. This server enables task management, project tracking, team collaboration, and workflow automation through 96 tools across 12 categories. + +## Features + +- **Task Management**: Create, update, delete, search, and manage tasks with full support for subtasks, dependencies, and custom fields +- **Project Operations**: Full project lifecycle management including creation, updates, task organization, and project status tracking +- **Workspace & Teams**: Manage workspaces, teams, team memberships, and organizational structure +- **User Management**: List users, get user details, manage favorites and task lists +- **Sections & Organization**: Create and manage sections within projects for better task organization +- **Tags & Custom Fields**: Apply tags for categorization and leverage custom fields for metadata +- **Goals & Portfolios**: Track high-level goals and organize projects into portfolios +- **Status Updates**: Post and manage project status updates for stakeholder communication +- **Webhooks**: Set up real-time webhooks for event-driven integrations +- **16 React Apps**: Pre-built UI components for task boards, project dashboards, team views, and more +- **Advanced Search**: Query tasks and projects with complex filters and field selections +- **Rate Limiting**: Built-in 150 requests/minute rate limiting with automatic retry + +## Installation + +```bash +npm install && npm run build +``` + +## Environment Variables + +| Variable | Required | Description | Example | +|----------|----------|-------------|---------| +| `ASANA_ACCESS_TOKEN` | Yes | Your Asana Personal Access Token (PAT) | `1/1234567890abcdef:fedcba0987654321` | + +## Getting Your Access Token + +1. **Log in to Asana**: Go to [app.asana.com](https://app.asana.com) +2. **Open Developer Console**: Click your profile photo → **Settings** → **Apps** tab +3. **Create Personal Access Token**: + - Scroll to "Personal access tokens" section + - Click **+ New access token** + - Enter a descriptive name (e.g., "MCP Server Integration") + - Click **Create token** +4. **Copy Your Token**: The token will be displayed once — copy it immediately and store it securely +5. **Set Environment Variable**: Add to your shell profile or `.env` file: + ```bash + export ASANA_ACCESS_TOKEN="your_token_here" + ``` + +**Security Note**: Personal Access Tokens have the same permissions as your user account. Keep them secure and never commit them to version control. + +## Required API Scopes + +Asana Personal Access Tokens automatically inherit all permissions from your user account. The server uses these API capabilities: + +- **Tasks**: Read, create, update, delete tasks and subtasks +- **Projects**: Read, create, update, delete projects +- **Workspaces & Organizations**: Read workspace and organization data +- **Teams**: Read team information and memberships +- **Users**: Read user profiles and task assignments +- **Custom Fields**: Read and write custom field values +- **Tags**: Create and apply tags +- **Goals**: Read and update goal data +- **Portfolios**: Read and manage portfolios +- **Status Updates**: Post project status updates +- **Webhooks**: Create and manage webhooks +- **Attachments**: Upload and manage file attachments + +## Usage + +### stdio Mode (Default) + +Add to your MCP client configuration (e.g., Claude Desktop): + +```json +{ + "mcpServers": { + "asana": { + "command": "node", + "args": [ + "/path/to/mcpengine-repo/servers/asana/dist/index.js" + ], + "env": { + "ASANA_ACCESS_TOKEN": "your_token_here" + } + } + } +} +``` + +### HTTP Mode + +The server can also run as an HTTP endpoint: + +```bash +export ASANA_ACCESS_TOKEN="your_token_here" +npm start -- --http --port 3000 +``` + +Then configure your MCP client to connect to `http://localhost:3000`. + +## Coverage Manifest + +``` +Total API endpoints: ~350 (Asana REST API v1.0) +Tools implemented: 96 +Intentionally skipped: ~200 (deprecated endpoints, admin-only features, edge cases) +Not yet covered: ~54 (attachments, stories, organization exports, batch operations) +Coverage: 96/350 = 27% +``` + +**Coverage Notes**: +- ✅ **Complete**: Tasks (6 tools), Projects (8 tools), Workspaces (4 tools), Teams (8 tools), Users (8 tools), Sections (8 tools), Tags (8 tools), Goals (8 tools), Portfolios (8 tools), Custom Fields (8 tools), Status Updates (8 tools), Webhooks (8 tools) +- ⏭️ **Skipped**: Type-ahead autocomplete, deprecated workspace APIs, organization-level admin operations +- 🚧 **Planned**: Attachment management, task stories/comments, audit logs, batch operations, time tracking + +## Example Use Cases + +- "Create a new task in the Marketing project assigned to Sarah, due next Friday" +- "List all tasks assigned to me that are due this week" +- "Update the Q1 Planning project status to 'On Track'" +- "Create a new portfolio called 'Product Initiatives' and add 3 projects to it" +- "Set up a webhook to notify when tasks are completed in the Engineering workspace" +- "Get all custom fields for the Design project" + +## Architecture + +The server uses lazy-loaded tool modules for optimal performance: +- **Client**: `AsanaClient` with rate limiting (150 req/min) +- **Tools**: 12 tool modules with 96 total tools +- **Apps**: 16 React-based UI components +- **Auth**: Bearer token authentication +- **Pagination**: Automatic offset-based pagination for list operations + +## Links + +- [Asana API Documentation](https://developers.asana.com/docs) +- [Asana API Explorer](https://developers.asana.com/explorer) +- [Rate Limits](https://developers.asana.com/docs/rate-limits) +- [Webhooks Guide](https://developers.asana.com/docs/webhooks-guide) diff --git a/servers/close/README.md b/servers/close/README.md new file mode 100644 index 0000000..c57f5ea --- /dev/null +++ b/servers/close/README.md @@ -0,0 +1,147 @@ +# Close CRM MCP Server + +A comprehensive Model Context Protocol (MCP) server for Close CRM, providing AI assistants with complete access to sales pipeline management, lead tracking, and customer relationship workflows. This server delivers 70 tools across sales activities, contact management, and pipeline automation. + +## Features + +- **Lead Management**: Create, search, update, and manage leads with custom fields and status tracking +- **Contact Operations**: Full CRUD operations for contacts with email, phone, and social profile management +- **Opportunity Pipeline**: Track deals through your sales pipeline with custom stages and values +- **Activity Tracking**: Log calls, emails, meetings, and notes with automatic activity timelines +- **Task Management**: Create and assign tasks with due dates, reminders, and priority levels +- **Custom Fields**: Leverage custom fields on leads, contacts, and opportunities for tailored workflows +- **Smart Views**: Access saved filters and custom views for quick data access +- **Sequences**: Manage email sequences and cadences for automated outreach +- **Reporting**: Generate pipeline reports, activity summaries, and team performance metrics +- **Bulk Operations**: Import, export, and update records in bulk +- **User & Team Management**: Manage team members, roles, and permissions +- **Advanced Search**: Query leads, contacts, and opportunities with complex filters + +## Installation + +```bash +npm install && npm run build +``` + +## Environment Variables + +| Variable | Required | Description | Example | +|----------|----------|-------------|---------| +| `CLOSE_API_KEY` | Yes | Your Close API key | `api_xxxxxxxxxxxxxxxxxxxxxxxx` | + +## Getting Your Access Token + +1. **Log in to Close**: Go to [app.close.com](https://app.close.com) +2. **Navigate to Settings**: Click the gear icon ⚙️ in the bottom left → **Settings** +3. **API Keys Section**: + - In the left sidebar, click **Developer** → **API Keys** + - Or go directly to: `https://app.close.com/settings/developer/api-keys/` +4. **Create API Key**: + - Click **Create new API key** + - Enter a name (e.g., "MCP Server Integration") + - Select access level (usually "Full Access" for MCP integration) + - Click **Create API Key** +5. **Copy Your Key**: The API key will be displayed once — copy it immediately +6. **Set Environment Variable**: + ```bash + export CLOSE_API_KEY="api_xxxxxxxxxxxxxxxxxxxxxxxx" + ``` + +**Security Note**: API keys inherit the permissions of the user who created them. Use service accounts or restricted users for production integrations. Never commit API keys to version control. + +## Required API Scopes + +Close API keys can have different access levels: + +**Full Access** (recommended for MCP): +- **Leads**: Read, create, update, delete leads +- **Contacts**: Read, create, update, delete contacts +- **Opportunities**: Read, create, update, close deals +- **Activities**: Log and read calls, emails, meetings, notes +- **Tasks**: Create and manage tasks +- **Custom Fields**: Read and write custom field values +- **Users**: Read user and team information +- **Smart Views**: Access saved searches and filters +- **Sequences**: Manage email sequences +- **Reporting**: Generate reports and analytics +- **Bulk Operations**: Import/export data + +**Read-Only**: Limited to viewing data (not recommended for full MCP functionality) + +**Custom**: Select specific permissions per resource type + +## Usage + +### stdio Mode (Default) + +Add to your MCP client configuration (e.g., Claude Desktop): + +```json +{ + "mcpServers": { + "close": { + "command": "node", + "args": [ + "/path/to/mcpengine-repo/servers/close/dist/index.js" + ], + "env": { + "CLOSE_API_KEY": "your_api_key_here" + } + } + } +} +``` + +### HTTP Mode + +The server can also run as an HTTP endpoint: + +```bash +export CLOSE_API_KEY="your_api_key_here" +npm start -- --http --port 3000 +``` + +Then configure your MCP client to connect to `http://localhost:3000`. + +## Coverage Manifest + +``` +Total API endpoints: ~120 (Close API v1) +Tools implemented: 70 +Intentionally skipped: ~30 (webhooks, integrations, SMS, custom email templates) +Not yet covered: ~20 (graph/timeline endpoints, merge operations, import status) +Coverage: 70/120 = 58% +``` + +**Coverage Notes**: +- ✅ **Complete**: Leads (10 tools), Contacts (9 tools), Opportunities (9 tools), Activities (12 tools), Tasks (6 tools), Custom Fields (6 tools), Users (5 tools), Smart Views (4 tools), Sequences (5 tools), Reporting (4 tools) +- ⏭️ **Skipped**: Webhooks (use Zapier/n8n), SMS activities, integration-specific endpoints, Zoom meeting creation +- 🚧 **Planned**: Lead/contact merge, bulk import status tracking, export jobs, connected accounts + +## Example Use Cases + +- "Create a new lead for Acme Corp with contact details for their CEO" +- "Show me all leads in the 'Qualified' status assigned to Sarah" +- "Log a call with John Smith about pricing discussion" +- "Create a follow-up task for tomorrow to send proposal to lead #12345" +- "Update the opportunity value to $50k and move to 'Negotiation' stage" +- "Search for all contacts with '@gmail.com' emails" +- "Get pipeline report for this month showing all won deals" +- "Add a lead to the 'New Customer Outreach' sequence" + +## Architecture + +The server uses a clean, modular architecture: +- **Client**: `CloseClient` with Basic Auth (API key + colon encoding) +- **Tools**: 12 tool modules with 70 total tools +- **Auth**: HTTP Basic Authentication (`api_key:` base64-encoded) +- **Pagination**: Automatic cursor-based pagination for list operations +- **Rate Limits**: Respects Close API rate limits (typically 600 req/min) + +## Links + +- [Close API Documentation](https://developer.close.com/) +- [Close API Reference](https://developer.close.com/resources/api-reference/) +- [Rate Limits](https://developer.close.com/resources/rate-limits/) +- [Custom Fields Guide](https://help.close.com/article/custom-fields/) +- [Close Help Center](https://help.close.com/) diff --git a/servers/freshdesk/README.md b/servers/freshdesk/README.md new file mode 100644 index 0000000..f3d04ef --- /dev/null +++ b/servers/freshdesk/README.md @@ -0,0 +1,163 @@ +# Freshdesk MCP Server + +A comprehensive Model Context Protocol (MCP) server for Freshdesk, providing AI assistants with complete access to customer support helpdesk operations. This server delivers 98 tools covering ticket management, agent operations, knowledge base, and customer engagement workflows. + +## Features + +- **Ticket Management**: Create, update, search, and resolve tickets with full SLA tracking and priority management +- **Contact & Company Management**: Comprehensive CRUD operations for contacts and companies with custom field support +- **Agent Operations**: Manage agents, roles, skills, and team assignments +- **Canned Responses**: Access and use pre-written response templates for faster ticket resolution +- **Knowledge Base**: Manage solutions, articles, categories, and forums for self-service support +- **Groups & Roles**: Organize agents into groups with role-based permissions +- **Products**: Track product-specific issues and categorize tickets by product +- **Survey Management**: Create and send customer satisfaction surveys +- **Reporting**: Generate ticket analytics, agent performance reports, and SLA compliance metrics +- **Automation**: Leverage Freshdesk's automation rules through API-driven ticket updates +- **Multi-Channel Support**: Handle tickets from email, chat, phone, and social media +- **Custom Fields**: Extensive custom field support for tickets, contacts, and companies + +## Installation + +```bash +npm install && npm run build +``` + +## Environment Variables + +| Variable | Required | Description | Example | +|----------|----------|-------------|---------| +| `FRESHDESK_API_KEY` | Yes | Your Freshdesk API key | `aBcDeFgHiJkLmNoPqRs` | +| `FRESHDESK_DOMAIN` | Yes | Your Freshdesk subdomain (without .freshdesk.com) | `yourcompany` | + +## Getting Your Access Token + +1. **Log in to Freshdesk**: Go to `https://yourcompany.freshdesk.com` +2. **Navigate to Profile Settings**: + - Click your profile picture in the top right + - Select **Profile settings** +3. **Locate API Key**: + - Look for the **Your API Key** section in the right sidebar + - Your API key will be displayed (it may be hidden behind asterisks) + - Click **Show** or **View full key** to reveal it +4. **Copy Your API Key**: Copy the full key (typically 20-21 characters) +5. **Set Environment Variables**: + ```bash + export FRESHDESK_API_KEY="aBcDeFgHiJkLmNoPqRs" + export FRESHDESK_DOMAIN="yourcompany" + ``` + +**Alternative Method** (Admin): +- Go to **Admin** → **API** section +- Your API key is displayed at the top +- You can also regenerate it if needed (this will invalidate the old key) + +**Security Note**: Each agent has their own API key with permissions matching their role. Use service/bot accounts for integrations. Never commit API keys to version control. + +## Required API Scopes + +Freshdesk API keys inherit the permissions of the user account: + +**Full Access** (Admin/Account Admin): +- **Tickets**: Read, create, update, delete, merge tickets +- **Contacts**: Read, create, update, delete contacts +- **Companies**: Read, create, update, delete companies +- **Agents**: Read, create, update, delete agents (admin only) +- **Roles**: Read role information +- **Groups**: Read, create, update, delete groups +- **Products**: Read, create, update, delete products +- **Solutions**: Read, create, update, delete KB articles +- **Forums**: Read, create, update, delete forum topics +- **Canned Responses**: Read and use canned responses +- **Surveys**: Read and send surveys +- **Reports**: Access reporting data + +**Agent Access**: +- Limited to tickets they have access to based on group membership +- Can read contacts and companies +- Cannot manage other agents or admin settings + +**Requester Access** (not recommended for MCP): +- Can only view their own tickets + +## Usage + +### stdio Mode (Default) + +Add to your MCP client configuration (e.g., Claude Desktop): + +```json +{ + "mcpServers": { + "freshdesk": { + "command": "node", + "args": [ + "/path/to/mcpengine-repo/servers/freshdesk/dist/index.js" + ], + "env": { + "FRESHDESK_API_KEY": "your_api_key_here", + "FRESHDESK_DOMAIN": "yourcompany" + } + } + } +} +``` + +### HTTP Mode + +The server can also run as an HTTP endpoint: + +```bash +export FRESHDESK_API_KEY="your_api_key_here" +export FRESHDESK_DOMAIN="yourcompany" +npm start -- --http --port 3000 +``` + +Then configure your MCP client to connect to `http://localhost:3000`. + +## Coverage Manifest + +``` +Total API endpoints: ~140 (Freshdesk API v2) +Tools implemented: 98 +Intentionally skipped: ~25 (time tracking, business hours, SLA policies, email configs) +Not yet covered: ~17 (ticket fields admin, automations, workflows, satisfaction ratings) +Coverage: 98/140 = 70% +``` + +**Coverage Notes**: +- ✅ **Complete**: Tickets (15 tools), Contacts (10 tools), Companies (8 tools), Agents (9 tools), Groups (6 tools), Products (6 tools), Canned Responses (6 tools), Solutions/KB (14 tools), Forums (10 tools), Roles (6 tools), Surveys (4 tools), Reporting (4 tools) +- ⏭️ **Skipped**: Time tracking (separate billing addon), business hours configuration, SLA policy management, email server configs, SSO settings +- 🚧 **Planned**: Custom ticket field administration, automation rule management, workflow triggers, CSAT rating retrieval, email template management + +## Example Use Cases + +- "Create a new support ticket from john@example.com about billing issue" +- "Update ticket #1234 status to 'Pending' and add internal note" +- "Search for all open tickets assigned to Sarah with high priority" +- "Get customer contact details for support@company.com" +- "Create a new solution article in the Getting Started category" +- "List all canned responses in the Billing Responses folder" +- "Add a new contact for Jane Smith at Acme Corp" +- "Merge ticket #5678 into ticket #1234" +- "Get all tickets created in the last 24 hours" +- "Assign ticket #9999 to the Sales Support group" + +## Architecture + +The server uses Freshdesk API v2 with Basic Authentication: +- **Client**: `FreshDeskClient` with Basic Auth (`apiKey:X` base64-encoded) +- **Tools**: 12 tool modules with 98 total tools +- **Auth**: HTTP Basic Authentication (API key with 'X' as password) +- **Pagination**: Automatic page-based pagination (30 records per page default) +- **Rate Limits**: Respects Freshdesk rate limits (varies by plan, typically 1000-5000 req/hr) +- **Domain**: All requests to `https://{domain}.freshdesk.com/api/v2` + +## Links + +- [Freshdesk API Documentation](https://developers.freshdesk.com/api/) +- [API v2 Reference](https://developer.freshdesk.com/api/v2/) +- [Authentication Guide](https://developer.freshdesk.com/api/#authentication) +- [Rate Limits](https://developer.freshdesk.com/api/#ratelimit) +- [Error Codes](https://developer.freshdesk.com/api/#http-response-codes) +- [Freshdesk Support](https://support.freshdesk.com/) diff --git a/servers/google-console/README.md b/servers/google-console/README.md new file mode 100644 index 0000000..26d6f75 --- /dev/null +++ b/servers/google-console/README.md @@ -0,0 +1,194 @@ +# Google Search Console MCP Server + +A comprehensive Model Context Protocol (MCP) server for Google Search Console, providing AI assistants with powerful SEO insights and website performance data. This server delivers 26 tools for search analytics, URL inspection, sitemap management, and intelligent SEO recommendations. + +## Features + +- **Search Analytics**: Query search performance data with flexible dimensions (query, page, country, device) +- **Comparative Analysis**: Compare performance across time periods, identify trends and anomalies +- **Top Movers Detection**: Automatically identify queries with significant ranking changes +- **Device Analysis**: Compare mobile vs desktop performance metrics +- **Geographic Insights**: Analyze search traffic by country and region +- **URL Inspection**: Deep-dive into indexing status, crawl details, and page experience metrics +- **Batch URL Inspection**: Inspect multiple URLs simultaneously for indexing issues +- **Indexing API**: Request indexing or removal for specific URLs +- **Sitemap Management**: Submit, update, and monitor sitemap processing status +- **Property Management**: List and verify Search Console properties +- **SEO Intelligence**: Detect quick wins, keyword cannibalization, and content decay +- **Query Clustering**: Group related search queries for content strategy insights +- **Discovery Tools**: Interactive tool discovery and capability exploration + +## Installation + +```bash +npm install && npm run build +``` + +## Environment Variables + +Google Search Console uses OAuth 2.0 authentication. You can provide credentials via environment variables or a JSON file: + +| Variable | Required | Description | Example | +|----------|----------|-------------|---------| +| `GSC_OAUTH_CLIENT_ID` | Yes* | OAuth 2.0 Client ID | `123456789-abc.apps.googleusercontent.com` | +| `GSC_OAUTH_CLIENT_SECRET` | Yes* | OAuth 2.0 Client Secret | `GOCSPX-aBcDeFgHiJkLmNoPqRsTuV` | +| `GSC_OAUTH_REDIRECT_URI` | No | OAuth redirect URI (default: `http://localhost:3000/oauth2callback`) | `http://localhost:3000/oauth2callback` | +| `GSC_OAUTH_CLIENT_FILE` | Yes* | Path to OAuth client JSON file (alternative to individual vars) | `/path/to/client_secret.json` | + +\* Either provide `GSC_OAUTH_CLIENT_ID` + `GSC_OAUTH_CLIENT_SECRET`, **OR** provide `GSC_OAUTH_CLIENT_FILE` + +## Getting Your Access Token + +### Step 1: Create OAuth 2.0 Credentials + +1. **Go to Google Cloud Console**: Visit [console.cloud.google.com](https://console.cloud.google.com) +2. **Create or Select Project**: + - Click the project dropdown at the top + - Click **New Project** or select an existing one +3. **Enable APIs**: + - Navigate to **APIs & Services** → **Library** + - Search for and enable: + - **Google Search Console API** + - **Web Search Indexing API** (optional, for indexing features) +4. **Configure OAuth Consent Screen**: + - Go to **APIs & Services** → **OAuth consent screen** + - Select **External** (or Internal if using Google Workspace) + - Fill in app name (e.g., "MCP Search Console Integration") + - Add your email as developer contact + - Add scopes (see Required API Scopes below) + - Add your email as a test user + - Save and continue +5. **Create OAuth Client ID**: + - Go to **APIs & Services** → **Credentials** + - Click **+ Create Credentials** → **OAuth client ID** + - Application type: **Desktop app** (recommended) or **Web application** + - Name: "MCP Server" + - For Web application, add authorized redirect URI: `http://localhost:3000/oauth2callback` + - Click **Create** +6. **Download Credentials**: + - Click the download button (⬇️) next to your newly created OAuth client + - Save the JSON file as `client_secret.json` + +### Step 2: Configure Environment + +Choose **one** of these methods: + +**Method A: Use JSON file** (recommended) +```bash +export GSC_OAUTH_CLIENT_FILE="/path/to/client_secret.json" +``` + +**Method B: Use individual environment variables** +```bash +export GSC_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com" +export GSC_OAUTH_CLIENT_SECRET="GOCSPX-your-secret" +export GSC_OAUTH_REDIRECT_URI="http://localhost:3000/oauth2callback" +``` + +### Step 3: First-Time Authentication + +When you first run the server, it will: +1. Open your browser to Google's OAuth consent page +2. Ask you to grant permissions +3. Redirect to localhost and exchange the code for tokens +4. Save tokens to `~/.gsc-mcp/oauth-token.json` + +Subsequent runs will use the saved refresh token automatically. + +## Required API Scopes + +The server requests these OAuth 2.0 scopes: + +- `https://www.googleapis.com/auth/webmasters` - Full access to Search Console data +- `https://www.googleapis.com/auth/webmasters.readonly` - Read-only access (fallback) +- `https://www.googleapis.com/auth/indexing` - Submit URLs for indexing + +**Permissions Required**: +- Read search performance data +- Inspect URL indexing status +- Submit and manage sitemaps +- Request indexing for URLs +- Verify site ownership +- Access all properties you own or have been granted access to + +**Note**: You must be verified as the owner or have delegated access to a Search Console property to query its data. + +## Usage + +### stdio Mode (Default) + +Add to your MCP client configuration (e.g., Claude Desktop): + +```json +{ + "mcpServers": { + "google-console": { + "command": "node", + "args": [ + "/path/to/mcpengine-repo/servers/google-console/dist/index.js" + ], + "env": { + "GSC_OAUTH_CLIENT_FILE": "/path/to/client_secret.json" + } + } + } +} +``` + +### HTTP Mode + +The server can also run as an HTTP endpoint: + +```bash +export GSC_OAUTH_CLIENT_FILE="/path/to/client_secret.json" +npm start -- --http --port 3000 +``` + +Then configure your MCP client to connect to `http://localhost:3000`. + +## Coverage Manifest + +``` +Total API endpoints: ~35 (Google Search Console API + Web Search Indexing API) +Tools implemented: 26 +Intentionally skipped: ~5 (admin notifications, AMP reports, mobile usability legacy endpoints) +Not yet covered: ~4 (Core Web Vitals detailed reports, manual actions, security issues) +Coverage: 26/35 = 74% +``` + +**Coverage Notes**: +- ✅ **Complete**: Search Analytics (5 tools), Discovery & Property Management (3 tools), URL Inspection (3 tools), Indexing API (1 tool), Sitemaps (3 tools), SEO Intelligence (4 tools), Advanced Analytics (7 tools) +- ⏭️ **Skipped**: AMP-specific reports (deprecated), mobile usability (migrated to Page Experience), admin email notifications +- 🚧 **Planned**: Core Web Vitals field data export, manual action details, security issue alerts, rich results testing + +## Example Use Cases + +- "Show me search analytics for my site in the last 28 days" +- "Which queries had the biggest ranking improvements this month?" +- "Compare mobile vs desktop click-through rates" +- "Inspect the indexing status of https://example.com/new-page" +- "Detect quick SEO wins for pages with high impressions but low CTR" +- "Find keyword cannibalization issues across my site" +- "Request indexing for my new blog post" +- "Get top pages by country breakdown" +- "Identify content that's decaying in search performance" +- "Submit a new sitemap to Search Console" + +## Architecture + +The server uses OAuth 2.0 with token persistence: +- **Auth**: OAuth 2.0 with interactive browser flow on first run +- **Token Storage**: Refresh tokens saved to `~/.gsc-mcp/oauth-token.json` +- **Client**: `google-auth-library` with automatic token refresh +- **APIs**: Search Console API v1, Web Search Indexing API v3 +- **Tools**: 6 tool modules with 26 total tools +- **Rate Limits**: Google API quotas (600 queries/minute, 2000/day for Search Console) + +## Links + +- [Google Search Console](https://search.google.com/search-console) +- [Search Console API Documentation](https://developers.google.com/webmaster-tools/v1/api_reference_index) +- [Web Search Indexing API](https://developers.google.com/search/apis/indexing-api/v3/quickstart) +- [OAuth 2.0 Setup Guide](https://developers.google.com/identity/protocols/oauth2) +- [API Quotas & Limits](https://developers.google.com/webmaster-tools/v1/limits) +- [Search Console Help](https://support.google.com/webmasters/) diff --git a/servers/gusto/README.md b/servers/gusto/README.md new file mode 100644 index 0000000..9b66608 --- /dev/null +++ b/servers/gusto/README.md @@ -0,0 +1,195 @@ +# Gusto MCP Server + +A comprehensive Model Context Protocol (MCP) server for Gusto, providing AI assistants with complete access to payroll, HR, and benefits management. This server delivers 59 tools covering employee management, payroll processing, benefits administration, and compliance workflows. + +## Features + +- **Employee Management**: Full CRUD operations for employees with onboarding, termination, and profile management +- **Payroll Processing**: Run payroll, manage pay schedules, view payroll summaries and history +- **Compensation Management**: Manage salaries, hourly rates, bonuses, commissions, and pay adjustments +- **Contractor Operations**: Track contractors, manage contractor payments, and 1099 reporting +- **Benefits Administration**: Manage health insurance, retirement plans (401k), and employee benefit elections +- **Time Off Tracking**: Manage PTO policies, vacation accruals, sick leave, and time-off requests +- **Tax Management**: Handle federal, state, and local tax withholdings and filings +- **Bank Account Management**: Configure company and employee bank accounts for direct deposit +- **Garnishments**: Process wage garnishments, child support, and other deductions +- **Company Information**: Manage company profiles, locations, and organizational settings +- **Compliance**: Ensure payroll tax compliance, I-9 verification, and benefits enrollment +- **Reporting**: Generate payroll reports, employee census data, and tax summaries + +## Installation + +```bash +npm install && npm run build +``` + +## Environment Variables + +| Variable | Required | Description | Example | +|----------|----------|-------------|---------| +| `GUSTO_API_TOKEN` | Yes | Your Gusto API access token | `de4dbeef1234567890abcdef` | + +## Getting Your Access Token + +### For Production Use (OAuth 2.0 - Recommended) + +Gusto uses OAuth 2.0 for third-party integrations. This is a multi-step process: + +1. **Register as a Gusto Partner**: + - Go to [dev.gusto.com](https://dev.gusto.com) + - Click **Get Started** and complete partner application + - Wait for approval (typically 1-3 business days) + +2. **Create an Application**: + - Log in to [Gusto Partner Dashboard](https://dev.gusto.com/partner-center) + - Click **Create Application** + - Enter application name and description + - Set redirect URI (e.g., `http://localhost:3000/callback`) + - Copy your **Client ID** and **Client Secret** + +3. **OAuth Flow**: + - Direct users to: `https://api.gusto.com/oauth/authorize?client_id={CLIENT_ID}&response_type=code&redirect_uri={REDIRECT_URI}` + - User authorizes your app and is redirected with an authorization code + - Exchange code for access token: + ```bash + curl -X POST https://api.gusto.com/oauth/token \ + -d "client_id={CLIENT_ID}" \ + -d "client_secret={CLIENT_SECRET}" \ + -d "code={AUTH_CODE}" \ + -d "redirect_uri={REDIRECT_URI}" \ + -d "grant_type=authorization_code" + ``` + - Save the `access_token` from the response + +4. **Set Environment Variable**: + ```bash + export GUSTO_API_TOKEN="your_access_token_here" + ``` + +### For Development/Testing (API Demo Token) + +1. **Log in to Gusto Partner Dashboard**: Go to [dev.gusto.com/partner-center](https://dev.gusto.com/partner-center) +2. **Get Demo Token**: + - Navigate to **API Tokens** or **Demo Environment** + - Click **Generate Demo Token** + - This token works with Gusto's demo/sandbox companies +3. **Copy Token**: Copy the demo token +4. **Set Environment Variable**: + ```bash + export GUSTO_API_TOKEN="your_demo_token_here" + ``` + +**Important Notes**: +- Demo tokens only work with sandbox data (fake companies/employees) +- Production tokens require OAuth 2.0 authorization from real Gusto customers +- Tokens expire after 2 hours; use refresh tokens for production +- Always use HTTPS and secure token storage + +## Required API Scopes + +When requesting OAuth authorization, specify these scopes: + +**Core Scopes**: +- `employees:read` - Read employee information +- `employees:write` - Create and update employee records +- `payrolls:read` - View payroll data and history +- `payrolls:write` - Run payrolls and make adjustments +- `companies:read` - Access company information +- `companies:write` - Update company settings + +**Additional Scopes**: +- `benefits:read` - View benefits enrollment and plans +- `benefits:write` - Manage benefits elections +- `time_off:read` - View PTO balances and requests +- `time_off:write` - Approve time-off and manage policies +- `contractors:read` - View contractor information +- `contractors:write` - Manage contractor payments +- `compensations:read` - View salary and wage information +- `compensations:write` - Update compensation rates +- `garnishments:read` - View garnishment data +- `garnishments:write` - Process garnishments +- `bank_accounts:read` - View bank account information +- `bank_accounts:write` - Update bank accounts + +**Full Access**: Request all scopes with `*` (not recommended for security) + +## Usage + +### stdio Mode (Default) + +Add to your MCP client configuration (e.g., Claude Desktop): + +```json +{ + "mcpServers": { + "gusto": { + "command": "node", + "args": [ + "/path/to/mcpengine-repo/servers/gusto/dist/index.js" + ], + "env": { + "GUSTO_API_TOKEN": "your_token_here" + } + } + } +} +``` + +### HTTP Mode + +The server can also run as an HTTP endpoint: + +```bash +export GUSTO_API_TOKEN="your_token_here" +npm start -- --http --port 3000 +``` + +Then configure your MCP client to connect to `http://localhost:3000`. + +## Coverage Manifest + +``` +Total API endpoints: ~95 (Gusto API v1) +Tools implemented: 59 +Intentionally skipped: ~20 (custom earnings, earning types admin, locations, federal taxes detailed) +Not yet covered: ~16 (webhooks, documents, reports generation, PTO requests) +Coverage: 59/95 = 62% +``` + +**Coverage Notes**: +- ✅ **Complete**: Employees (12 tools), Payrolls (8 tools), Compensations (7 tools), Contractors (6 tools), Benefits (6 tools), Time Off (6 tools), Bank Accounts (5 tools), Garnishments (4 tools), Companies (3 tools), Tax Tools (2 tools) +- ⏭️ **Skipped**: Custom earning types configuration, location-specific settings, detailed tax form generation, historical payroll amendments +- 🚧 **Planned**: Webhook management, document uploads (W-4, I-9), payroll reports generation, PTO request workflow, terminated employee data retention + +## Example Use Cases + +- "Add a new employee named John Smith with email john@company.com" +- "Get payroll summary for the current pay period" +- "Update Sarah's salary to $85,000 annually effective next month" +- "List all contractors and their payment history" +- "Enroll employee #12345 in the company 401(k) plan" +- "Show me all employees with pending time-off requests" +- "Add bank account for direct deposit for new employee" +- "Process wage garnishment for $500/month for employee #789" +- "Get company tax information and EIN" +- "Run payroll for the current period" + +## Architecture + +The server uses Gusto API v1 with Bearer token authentication: +- **Client**: `GustoClient` with Bearer token auth +- **Tools**: 10 tool modules with 59 total tools +- **Auth**: HTTP Bearer Authentication (`Authorization: Bearer {token}`) +- **Pagination**: Automatic page-based pagination where supported +- **Rate Limits**: Respects Gusto rate limits (typically 100 requests/10 seconds) +- **Base URL**: `https://api.gusto.com/v1` (production) or `https://api.gusto-demo.com/v1` (demo) + +## Links + +- [Gusto Developer Portal](https://dev.gusto.com) +- [Gusto API Documentation](https://docs.gusto.com/app-integrations/docs) +- [API Reference](https://docs.gusto.com/app-integrations/reference) +- [OAuth 2.0 Guide](https://docs.gusto.com/app-integrations/docs/oauth) +- [Rate Limits](https://docs.gusto.com/app-integrations/docs/rate-limiting) +- [Partner Center](https://dev.gusto.com/partner-center) +- [Gusto Support](https://support.gusto.com/) diff --git a/servers/square/README.md b/servers/square/README.md new file mode 100644 index 0000000..98d64b5 --- /dev/null +++ b/servers/square/README.md @@ -0,0 +1,217 @@ +# Square MCP Server + +A comprehensive Model Context Protocol (MCP) server for Square, providing AI assistants with complete access to payment processing, point-of-sale operations, and business management. This server delivers 80 tools across payments, inventory, customers, and e-commerce workflows, plus 18 React-based UI applications. + +## Features + +- **Payment Processing**: Create, capture, void, and refund payments with support for all payment methods +- **Order Management**: Create orders, manage line items, apply discounts, calculate taxes, and track fulfillment +- **Customer Management**: Full CRM with customer profiles, groups, segments, and marketing preferences +- **Catalog & Inventory**: Manage products, variations, modifiers, categories, and real-time inventory tracking +- **Invoicing**: Create, send, update, and track invoices with payment reminders +- **Subscriptions**: Manage recurring billing, subscription plans, and customer subscriptions +- **Loyalty Programs**: Create loyalty programs, track points, and manage rewards +- **Team Management**: Manage team members, roles, wage settings, and permissions +- **Location Management**: Handle multiple business locations and location-specific settings +- **Booking & Appointments**: Manage appointment calendars, bookings, and service catalog +- **Dispute Handling**: Track payment disputes, submit evidence, and manage chargebacks +- **Refund Operations**: Process full and partial refunds with automatic inventory adjustment +- **18 React Apps**: Pre-built UI components for POS, inventory management, customer dashboards, and more +- **Multi-Currency Support**: Process payments in multiple currencies with automatic conversion +- **Sandbox Testing**: Full sandbox environment support for development and testing + +## Installation + +```bash +npm install && npm run build +``` + +## Environment Variables + +| Variable | Required | Description | Example | +|----------|----------|-------------|---------| +| `SQUARE_ACCESS_TOKEN` | Yes | Your Square access token (sandbox or production) | `EAAAEOuLQPTO1Z4...` | +| `SQUARE_ENVIRONMENT` | No | Environment: `sandbox` or `production` (default: `production`) | `sandbox` | + +## Getting Your Access Token + +### Production Token (Live Payments) + +1. **Create a Square Developer Account**: + - Go to [developer.squareup.com](https://developer.squareup.com) + - Click **Sign Up** or log in with your Square account + - Complete the developer registration + +2. **Create an Application**: + - Go to [Square Developer Dashboard](https://developer.squareup.com/apps) + - Click **+ Create App** or **New Application** + - Enter application name (e.g., "MCP Integration") + - Select your Square account to associate with the app + +3. **Get Production Access Token**: + - In your application dashboard, click **Production** tab + - Under **Credentials**, find **Access Token** + - Click **Show** to reveal the token + - Copy the entire token (starts with `EAA...`) + +4. **Set Environment Variables**: + ```bash + export SQUARE_ACCESS_TOKEN="your_production_token_here" + export SQUARE_ENVIRONMENT="production" + ``` + +### Sandbox Token (Testing) + +1. **Access Sandbox Credentials**: + - In your [application dashboard](https://developer.squareup.com/apps) + - Click the **Sandbox** tab (not Production) + - Under **Credentials**, find **Sandbox Access Token** + - Click **Show** to reveal the token + +2. **Set Environment Variables**: + ```bash + export SQUARE_ACCESS_TOKEN="your_sandbox_token_here" + export SQUARE_ENVIRONMENT="sandbox" + ``` + +3. **Test Data**: + - Sandbox uses fake credit cards: `4111 1111 1111 1111` (Visa) + - CVV: any 3 digits, Expiry: any future date + - Postal code: any 5-digit ZIP + - [Full test card list](https://developer.squareup.com/docs/testing/test-values) + +### OAuth 2.0 (For Third-Party Apps) + +If building an app for other Square merchants: + +1. **Enable OAuth**: In app settings, enable OAuth +2. **Set Redirect URL**: Add your OAuth callback URL +3. **Authorization Flow**: + - Direct user to: `https://connect.squareup.com/oauth2/authorize?client_id={APP_ID}&scope={SCOPES}` + - User authorizes and redirects back with code + - Exchange code for access token at `/oauth2/token` endpoint + +**Security Notes**: +- Never commit access tokens to version control +- Production tokens have full access to real payment data +- Rotate tokens regularly and use OAuth for third-party integrations +- Sandbox and production tokens are completely separate + +## Required API Scopes + +Square access tokens automatically include these permissions: + +**Payment Scopes**: +- `PAYMENTS_READ` - View payment history and details +- `PAYMENTS_WRITE` - Process payments, refunds, and voids +- `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` - Split payments to multiple recipients + +**Order & Catalog Scopes**: +- `ORDERS_READ` - View orders +- `ORDERS_WRITE` - Create and update orders +- `ITEMS_READ` - View catalog items and inventory +- `ITEMS_WRITE` - Manage products, variations, and inventory + +**Customer Scopes**: +- `CUSTOMERS_READ` - View customer data +- `CUSTOMERS_WRITE` - Create and update customers +- `MERCHANT_PROFILE_READ` - View business information +- `MERCHANT_PROFILE_WRITE` - Update business settings + +**Additional Scopes**: +- `INVOICES_READ` / `INVOICES_WRITE` - Manage invoices +- `SUBSCRIPTIONS_READ` / `SUBSCRIPTIONS_WRITE` - Manage subscriptions +- `APPOINTMENTS_READ` / `APPOINTMENTS_WRITE` - Manage bookings +- `LOYALTY_READ` / `LOYALTY_WRITE` - Manage loyalty programs +- `TIMECARDS_READ` / `TIMECARDS_WRITE` - Manage team time tracking +- `DISPUTES_READ` / `DISPUTES_WRITE` - Handle payment disputes +- `GIFTCARDS_READ` / `GIFTCARDS_WRITE` - Manage gift cards + +**OAuth Scope Format**: When using OAuth, request specific scopes in the authorization URL (space-separated list). + +## Usage + +### stdio Mode (Default) + +Add to your MCP client configuration (e.g., Claude Desktop): + +```json +{ + "mcpServers": { + "square": { + "command": "node", + "args": [ + "/path/to/mcpengine-repo/servers/square/dist/index.js" + ], + "env": { + "SQUARE_ACCESS_TOKEN": "your_token_here", + "SQUARE_ENVIRONMENT": "sandbox" + } + } + } +} +``` + +### HTTP Mode + +The server can also run as an HTTP endpoint: + +```bash +export SQUARE_ACCESS_TOKEN="your_token_here" +export SQUARE_ENVIRONMENT="sandbox" +npm start -- --http --port 3000 +``` + +Then configure your MCP client to connect to `http://localhost:3000`. + +## Coverage Manifest + +``` +Total API endpoints: ~150 (Square API v2) +Tools implemented: 80 +Intentionally skipped: ~40 (gift cards, cash drawer, labor, terminal, devices, deprecated v1 endpoints) +Not yet covered: ~30 (bank accounts, payouts, cards on file, snippets, sites, mobile auth) +Coverage: 80/150 = 53% +``` + +**Coverage Notes**: +- ✅ **Complete**: Payments (8 tools), Orders (10 tools), Customers (9 tools), Catalog (9 tools), Inventory (7 tools), Invoices (8 tools), Subscriptions (7 tools), Locations (4 tools), Team Members (6 tools), Bookings (6 tools), Disputes (3 tools), Refunds (3 tools), Loyalty (8+ tools) +- ⏭️ **Skipped**: Gift cards (separate activation flow), cash drawer management, labor/shift tracking, terminal device pairing, deprecated v1 APIs, snippets/embeds +- 🚧 **Planned**: Bank account verification, payout schedules, saved payment methods (cards on file), marketing snippets, Square Sites integration, mobile authorization + +## Example Use Cases + +- "Process a $49.99 payment for customer john@example.com" +- "Create a new product 'Organic Coffee Beans' with price $24.99" +- "List all orders from the last 7 days" +- "Add customer Sarah Johnson with email sarah@example.com" +- "Refund payment #xyz123 for $10.00" +- "Update inventory count for product SKU 'BEANS-001' to 50 units" +- "Create an invoice for $500 due in 30 days" +- "List all team members at the Downtown location" +- "Get today's payment summary across all locations" +- "Create a subscription plan for $29.99/month" + +## Architecture + +The server uses Square API v2 (2024-12-18) with Bearer token authentication: +- **Client**: `SquareClient` with automatic idempotency key generation +- **Tools**: 13 tool modules with 80 total tools +- **Apps**: 18 React-based UI components +- **Auth**: HTTP Bearer Authentication (`Authorization: Bearer {token}`) +- **Pagination**: Automatic cursor-based pagination +- **Idempotency**: Automatic UUID generation for idempotent operations +- **Retry Logic**: Built-in retry with exponential backoff (3 attempts, 1s delay) +- **Rate Limits**: Respects Square rate limits (varies by endpoint, typically 10-500 req/sec) +- **API Version**: `2024-12-18` (updates quarterly) + +## Links + +- [Square Developer Portal](https://developer.squareup.com) +- [Square API Reference](https://developer.squareup.com/reference/square) +- [API Explorer](https://developer.squareup.com/explorer/square) +- [OAuth Guide](https://developer.squareup.com/docs/oauth-api/overview) +- [Testing Guide](https://developer.squareup.com/docs/testing/test-values) +- [Sandbox Dashboard](https://developer.squareup.com/apps) +- [API Changelog](https://developer.squareup.com/docs/changelog) +- [Square Support](https://squareup.com/help)